On This Page
REST API
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:
- Create and send the invoice immediately.After the API creates the invoice and sends it successfully, it sets the invoicestatustoSENT.To create this type of invoice, set the following fields within theinvoiceInformationobject:
- SetsendImmediatelytotrue.
- SetdeliveryModetoemail.
- Create and publish the invoice without sending an emailAfter the API creates the invoice, it sets the invoicestatustoCREATED. The API does not send an invoice to the customer, but you and your customer can view the invoice at theinvoiceInformation.paymentLinkURL.To create this type of invoice, set the following fields within theinvoiceInformationobject:
- SetsendImmediatelytotrue.
- SetdeliveryModetonone.
- Create a draft (unpublished) invoice.After the API creates this type of invoice, it sets the invoicestatustoDRAFT. A draft invoice is not published nor sent. It does not have aninvoiceInformation.paymentLinkvalue, and your customer cannot view it.To create a draft invoice, set the following fields within theinvoiceInformationobject:
- SetsendImmediatelytofalse.
- SetdeliveryModeto one of these options:
- email— When you later send an invoice with this delivery mode, the API changes the invoicestatustoSENTand sends an email to the customer.
- none— When you later send an invoice with this delivery mode, the API changes the invoicestatustoCREATEDand does not send an email to the customer. However, you can view the invoice at the URL returned in theinvoiceInformation.paymentLinkresponse 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. - Links
- To get the invoice details again, use theselflink path:https://apitest.cybersource.com/v2/invoices/A123456
- Supported Actions
- Use thedeliveryaction 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 thecancelationaction to cancel an invoice. See Cancel an Invoice for details.
- Use thePUTHTTP 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.