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:
- Test:POSThttps://apitest.cybersource.com/invoicing/v2/invoices
- Live:POSThttps://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.
All
Cybersource
APIs require API authentication. See
Getting Started with the REST API
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 email.After 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.IMPORTANT
You cannot update the invoice number later.
Request example:
This example shows you how to create a new invoice and send it
immediately. An invoice can include up to 30 line items, in the lineItems
object.{ "customerInformation": { "name": "Tanya Lee", "email": "[email protected]" }, "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://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": "[email protected]" }, "invoiceInformation": { "invoiceNumber": "A123456", "description": "This is a test invoice", "dueDate": "2019-07-11" "paymentLink": "https://businesscenter.cybersource.com/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" }] } }