On This Page

Create and Send an Invoice Immediately

Creating and sending an invoice publishes a payable invoice that is automatically emailed to the customer. In addition to the sent email, you can also share the invoice by sending the customer the redirect URL generated in the

invoiceInformation.paymentLink

response field.

Itemized Invoices

An invoice can display a single billed amount or list up to 30 billed items. To list the billed items in the invoice, include the items in the request using the line item array fields. An invoice with line items is known as an itemized
invoice. For more information about how to include line items in your request, see Including Line Items in an Invoice.

Invoice Numbers

You can assign a unique invoice number in the

invoiceInformation.invoiceNumber

request field. The invoice number is required for follow-on API requests and tracking. You should store the invoice number in your system so that you can optimally perform the follow-on requests. If you do not include a unique invoice number when creating an invoice, Cybersource generates a unique invoice number for you in the

invoiceInformation.invoiceNumber

response field.

IMPORTANT

You cannot update the invoice number after it is generated.

Installment Payments

Invoices can be paid in installment payments when these fields and values are included in the request. If an invoice is payable in installments, multiple customers can make payments towards the same invoice.

invoiceInformation.allowPartialPayments: Set to
true
.
orderInformation.amountDetails.minimumPartialAmount: Set to the minimum amount allowed for a partial payment.

Partner Information

If your merchant account is associated with a Cybersource partner, you can include your partner solution ID (PSID) in the request message for tracking and reporting purposes. To include your PSID, use the

clientReferenceInformation.partner.solutionId

request field and set its field value to your PSID.

Alternative Methods to Create an Invoice

To create a new invoice that is not
immediately sent in an email to the customer, see Create an Invoice without Sending it.

To create an invoice draft
that is not payable or viewable to the customer, see Create a Draft Invoice.

Endpoint

Send an API POST request message to one of these endpoints:

Test:

POST https://apitest.cybersource.com/invoicing/v2/invoices

Production:

POST https://api.cybersource.com/invoicing/v2/invoices

India Production:

POST https://api.in.cybersource.com/invoicing/v2/invoices

Successful Response

A successfully created and sent invoice is indicated by the

SENT

status in the

status

response field. The response message also includes the newly created invoice's details.

Follow-On API Requests

After creating an invoice, you can send these follow-on API requests.

Update an Invoice: To update customer information or item details in an invoice, send an update invoice request. For more information, see Update an Invoice.
Cancel an Invoice: To cancel an invoice, send a cancel invoice request. For more information, see Cancel an Invoice.
Get Invoice Details: You can retrieve an invoice's details by sending a get invoice details request. For more information, see Get Invoice Details.
Get List of Invoices: After creating multiple invoices, you might want to search for certain invoices. To retrieve a filtered list of invoices, send a get list of invoices request. For more information, see Get a List of Invoices.

Required Fields for Creating and Sending an Invoice

This section lists the required fields necessary to create and send these types of invoices:

Email invoice

Itemized email invoice

Required Fields for an Email Invoice

customerInformation.email
customerInformation.name
invoiceInformation.deliveryMode: Set to
email
.

invoiceInformation.description

invoiceInformation.dueDate
invoiceInformation.sendImmediately: Set to
true
.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

Required Fields for an Email Invoice with Line Items

customerInformation.email
customerInformation.name
invoiceInformation.deliveryMode: Set to
email
.
invoiceInformation.dueDate
invoiceInformation.sendImmediately: Set to
true
.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.lineItems[].productName
orderInformation.lineItems[].productSku
orderInformation.lineItems[].quantity
orderInformation.lineItems[].totalAmount
orderInformation.lineItems[].unitPrice

Optional Fields for Invoice Creation

You can include these optional fields when sending create invoice requests:

clientReferenceInformation.partner.developerId: Set to your developer ID.
clientReferenceInformation.partner.solutionId: Set to your partner solution ID (PSID).
customerInformation.company.name
customerInformation.email
customerInformation.merchantCustomerId
customerInformation.name
invoiceInformation.allowPartialPayments: Set to one of these possible values:
false
: The invoice must be paid in a single payment.
true
: The invoice is payable in installments.
invoiceInformation.deliveryMode
invoiceInformation.description: This field is optional when the line item fields are present in the request message.
invoiceInformation.invoiceNumber: Set to a unique number to create an invoice number.

If you do not include this field and a unique value, the invoicing API automatically generates an invoice number for the new invoice.

IMPORTANT

You cannot update this invoice number after sending the API request.
merchantDefinedFieldValues.definition id[].value
orderInformation.amountDetails.freight.amount
orderInformation.amountDetails.freight.taxable
orderInformation.amountDetails.freight.taxRate
orderInformation.amountDetails.minimumPartialAmount
orderInformation.amountDetails.subAmount

Example: Creating and Sending an Invoice

Request

{
  "customerInformation": {
    "email": "test@email.com"
  },
  "invoiceInformation": {
    "description": "This is a test invoice",
    "dueDate": "2019-07-11",
    "sendImmediately": true,
    "deliveryMode": "email"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "2623.64",
      "currency": "USD"
    }
  }
}

Response to a Successful Request

{
  "_links": {
    "self": {
      "href": "/v2/invoices/98768",
      "method": "GET"
    },
    "update": {
      "href": "/v2/invoices/98768",
      "method": "PUT"
    },
    "deliver": {
      "href": "/v2/invoices/98768/delivery",
      "method": "POST"
    },
    "cancel": {
      "href": "/v2/invoices/98768/cancelation",
      "method": "POST"
    }
  },
  "id": "98768",
  "submitTimeUtc": "2024-08-03T00:40:31.143121084Z",
  "status": "SENT",
  "customerInformation": {
    "email": "test@email.com"
  },
  "processingInformation": {
    "requestPhone": false,
    "requestShipping": false
  },
  "invoiceInformation": {
    "invoiceNumber": "98768",
    "description": "This is a test invoice",
    "dueDate": "2019-07-11",
    "allowPartialPayments": false,
    "paymentLink": "https://businesscenter.cybersource.com/ebc2/invoicing/payInvoice/2AgCNHLrUtD7hfFR5SVh5DSxISAbFD9zybhUjpxpZuXKLQVyuLttP78uWWLRSSNX?version=v2.1",
    "deliveryMode": "Email"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": 2623.64,
      "currency": "USD",
      "balanceAmount": 2623.64
    }
  }
}