Menu

Create a New Invoice

To create a new invoice, pass the invoice details to the invoices resource.
Use this resource to create a new invoice: 
Sandbox:
POST https://apitest.cybersource.com/invoicing/v2/invoices
Live:
POST https://api.cybersource.com/invoicing/v2/invoices
Live in India:
POST https://api.in.cybersource.com/invoicing/v2/invoices
For more details, see the Create a New Invoice section of the interactive API Reference.
Note:
All CyberSource APIs require API authentication. See Authentication for details.

Request

The create invoice request contains these objects:
  • customerInformation
  • invoiceInformation
  • orderInformation
You can create a new invoice in one of three ways:
  1. Create and send the invoice immediately.
    After the API creates the invoice and sends it successfully, it sets the invoice
    status
    to
    SENT
    .
    To create this type of invoice, set the following fields within the
    invoiceInformation
    object:
    • Set
      sendImmediately
      to
      true
      .
    • Set
      deliveryMode
      to
      email
      .
  2. Create and publish the invoice without sending an email
    After the API creates the invoice, it sets the invoice
    status
    to
    CREATED
    . The API does not send an invoice to the customer, but you and your customer can view the invoice at the
    invoiceInformation.paymentLink
    URL.
    To create this type of invoice, set the following fields within the
    invoiceInformation
    object:
    • Set
      sendImmediately
      to
      true
      .
    • Set
      deliveryMode
      to
      none
      .
  3. Create a draft (unpublished) invoice.
    After the API creates this type of invoice, it sets the invoice
    status
    to
    DRAFT
    .  A draft invoice is not published nor sent. It does not have an
    invoiceInformation.paymentLink
    value, and your customer cannot view it.
    To create a draft invoice, set the following fields within the
    invoiceInformation
    object:
    • Set
      sendImmediately
      to
      false
      .
    • Set
      deliveryMode
      to one of these options:
      • email
        — When you later send an invoice with this delivery mode, the API changes the invoice
        status
        to
        SENT
        and sends an email to the customer.
      • none
        — When you later send an invoice with this delivery mode, the API changes the invoice
        status
        to
        CREATED
        and does not send an email to the customer. However, you can view the invoice at the URL returned in the
        invoiceInformation.paymentLink
        response field. You can choose to provide your customers with this direct link to the invoice.
Assigning an invoice number
When you create a new invoice, you can choose to include an invoice number in the
invoiceInformation.invoiceNumber
field. If you do not include an invoice number, the Invoicing API automatically generates an invoice number for the new invoice.
Note:
You cannot update the invoice number later.
Request example:
This example shows you how to create a new invoice and send it immediately.
Note:
An invoice can include up to 30 line items, in the
lineItems
object.
{ "customerInformation": { "name": "Tanya Lee", "email": "tanya.lee@my-email.world" }, "invoiceInformation": { "invoiceNumber": "A123456", "description": "This is a test invoice", "dueDate": "2019-07-11", "sendImmediately": "true", "allowPartialPayments": "true", "deliveryMode": "email" }, "orderInformation": { "amountDetails": { "totalAmount": "2623.64", "currency": "USD", "discountAmount": "126.08", "discountPercent": "5", "subAmount": "2749.72", "minimumPartialAmount": "20", "taxDetails": { "type": "State Tax", "amount": "208.04", "rate": "8.25" }, "freight": { "amount": "20.00", "taxable": "true" } }, "lineItems": [{ "productSku": "P653727383", "productName": "First line item's name", "quantity": "21", "unitPrice": "120.08" }] } }

Response

If the request is successful, the API returns the details of the newly created invoice. The response also includes the
_links
and
_supportedActions
objects.
  1. Links
    • To get the invoice details again, use the
      self
      link path:
      https://apitest.cybersource.com/v2/invoices/A123456
  2. Supported Actions
    • Use the
      delivery
      action to send a draft or created invoice or to resend a sent or partially paid invoice. Paid or canceled invoices cannot be resent at this time. See Send an Invoice for details.
    • Use the
      cancelation
      action to cancel an invoice. See Cancel an Invoice for details.
    • Use the
      PUT
      HTTP method to update an invoice as long as no payment has been made on the invoice. See Update an Invoice for details.
Response example:
{ "_links": { "self": { "href": "/invoicing/v2/invoices/A123456", "method": "GET" } }, "_supportedActions": [{ "href": "/invoicing/v2/invoices/A123456/delivery", "method": "POST" }, { "href": "/invoicing/v2/invoices/A123456/cancelation", "method": "POST" }, { "href": "/invoicing/v2/invoices/A123456", "method": "PUT" }], "id": "A123456", "submitTimeUtc": "2020-02-10T06:32:06Z", "status": "SENT", "customerInformation": { "name": "Tanya Lee", "email": "tanya.lee@my-email.world" }, "invoiceInformation": { "invoiceNumber": "A123456", "description": "This is a test invoice", "dueDate": "2019-07-11" "paymentLink": "https://businesscenter.cybersource.com/ebc2/invoicing/payInvoice/c7UI9Vz8rdhXbc8FdK6SaoeOATON4TQLhbd5lfib9UCyywvZLhIrSuYYNFMynMDd" }, "orderInformation": { "amountDetails": { "totalAmount": "2623.64", "currency": "USD", "balanceAmount": "2623.64", "discountAmount": "126.08", "discountPercent": "5", "subAmount": "2749.72", "taxDetails": { "type": "State Tax", "amount": "208.04", "rate": "8.25" }, "freight": { "amount": "20.00", "taxable": "true" } }, "lineItems": [{ "productSku": "P653727383", "productName": "First line item's name", "quantity": "21", "unitPrice": "120.08" }] } }
For more details, see the Create a New Invoice section of the interactive API Reference.
Back to top