Create a Draft Invoice

On This Page
Drafting an invoice creates an unpublished invoice that is viewable only by you. When sending the draft invoice request, set the
invoiceInformation.deliveryMode
 field to
none
 to ensure that the invoice draft is not automatically sent in an email message to the customer when the invoice is published. When you are ready to publish the draft invoice, you can send a
send invoice
 request. After publishing the drafted invoice, the invoice's status updates from
DRAFT
 to
CREATED
.
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.
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
draft
 invoice that is sent in an email message to the customer when you publish it, see Create a Draft 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
and send
 a new invoice at the same time, see Create and Send an Invoice Immediately.

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
Production in India:
POST https://api.in.cybersource.com/invoicing/v2/invoices

Response to a Successful Request

A successfully drafted invoice is indicated by the
DRAFT
 status in the
status
 response field.
The redirect URL generated in the
invoiceInformation.paymentLink
 response field is usable only by you and not the customer.
Additional invoice details are included in the response message for you to review.

Follow-On API Requests

After successfully drafting an invoice, you can send these follow-on API requests.
Send an Invoice
After drafting an invoice, you can publish and send an invoice using the send invoice request. For more information, see Send an Invoice.
Update an Invoice
To update customer information or item details in an already drafted invoice, send an update invoice request. For more information, see Update an Invoice.
Cancel an Invoice
To cancel a drafted invoice, send the a cancel invoice request. For more information, see Cancel an Invoice.
Get Invoice Details
To retrieve a drafted invoice's details, send a get invoice details request. For more information, see Get Invoice Details.

Line Items

You can itemize invoices by using the line item fields when you create, draft, and update an invoice.
Line items
 are used to include information about your customers' purchases. Information can include product name, quantity, and price.
Line items are included in a request in the
lineItem[]
 array request field.
These fields are required for each line item in your request:
These fields are optional for each line item in your request:
Example: Including Line Items
This example shows three valid line items. 
{ 
  "orderInformation": {
    "lineItems": [
      {
        "productSku": "ABCD1234",
        "productName": "First line item's name",
        "quantity": "20",
        "unitPrice": "12.05",
        "discountAmount": "13.04",
        "taxAmount": "0.0",
        "taxRate": "0.0",
        "totalAmount": "247.86"
      },
      {
        "productSku": "EFGH5678",
        "productName": "Second line item's name",
        "quantity": "20",
        "unitPrice": "12.05",
        "discountAmount": "13.04",
        "taxAmount": "0.0",
        "taxRate": "0.0",
        "totalAmount": "247.86"
      },
      {
        "productSku": "IJKL9999",
        "productName": "Third line item's name",
        "quantity": "20",
        "unitPrice": "12.05",
        "discountAmount": "13.04",
        "taxAmount": "0.0",
        "taxRate": "0.0",
        "totalAmount": "247.86"
      }
    ]
  }
}

Required Fields for Drafting an Invoice

  • In-person draft invoice
  • Email draft invoice
  • Itemized email draft invoice
The invoice created using these fields and specified values is not immediately sent to the customer.

Required Fields for Drafting an In-Person Invoice

invoiceInformation.deliveryMode
Set to one of these possible values to determine whether or not the invoice is emailed to the customer when you send a send invoice request:
  • email
    : An invoice email is sent to the customer when you send the follow-on send invoice request for this invoice draft. The invoice status updates to
    SENT
    .
  • none
    : When you process a follow-on send invoice request to publish the drafted invoice, the invoice is not sent in an email to the customer. To share the invoice with the customer, send the customer the redirect URL in the
    invoiceInformation.paymentLink
     response field. The invoice updates change to
    CREATED
    .
invoiceInformation.description
invoiceInformation.dueDate
invoiceInformation.sendImmediately
Set to
false
.

Required Fields for Drafting an Email Invoice

customerInformation.email
customerInformation.name
invoiceInformation.deliveryMode
Set to
email
.
invoiceInformation.dueDate
invoiceInformation.sendImmediately
Set to
false
.

Required Fields for Drafting an Invoice with Line Items

customerInformation.email
customerInformation.name
invoiceInformation.deliveryMode
Set to one of these possible values to determine whether or not the invoice will be emailed to the customer when you send a send invoice request:
  • email
    : An invoice email is sent to the customer when you send the follow-on send invoice request for this invoice draft. The invoice status will change to
    SENT
    .
  • none
    : When you process a follow-on send invoice request to publish the drafted invoice, the invoice is not sent in an email to the customer. To share the invoice with the customer, send the customer the redirect URL in the
    invoiceInformation.paymentLink
     response field. The invoice status will change to
    CREATED
    .
invoiceInformation.dueDate
invoiceInformation.sendImmediately
Set to
false
.
orderInformation.lineItems[].productSku

Optional Fields for Invoice Creation

Set to your developer ID.
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 becomes optional when either one of these conditions is met:
  • The line item fields are present in the request message.
  • When drafting a deliverable invoice, the
    invoiceInformation.deliveryMode
     request field is set to
    email
    .
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

Optional Fields for Discounts and Taxes

IMPORTANT
You cannot include discounts or taxes to both the total billed amount and line items in the same request.
IMPORTANT
The merchant is responsible for complying with any legal and tax requirements when issuing invoices to clients.
Cybersource
 does not certify that the invoicing tool meets any such client requirements.

Discount Fields for the Invoice Total

orderInformation.amountDetails.discountPercent

Tax Fields for the Invoice Total

orderInformation.amountDetails.taxDetails.amount
orderInformation.amountDetails.taxDetails.rate
orderInformation.amountDetails.taxDetails.type

Example: Drafting an Invoice

REST Interactive Example: Create an Invoice Draft

Click this image to access the interactive code example for creating a invoice draft.

Figure:

Interactive Code
Image and link to the interactive code example for creating a new invoice.
Light Dark
Request
123456789101112
{"invoiceInformation": {
    "description": "Food",
    "dueDate": "2019-07-11",
    "sendImmediately": false,
    "deliveryMode": "none"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "2623.64",
      "currency": "USD"
    }
  }}
Response to a Successful Request
12345678910111213141516171819202122232425262728293031323334353637383940
{"_links": {
    "self": {
      "href": "/v2/invoices/98762",
      "method": "GET"
    },
    "update": {
      "href": "/v2/invoices/98762",
      "method": "PUT"
    },
    "deliver": {
      "href": "/v2/invoices/98762/delivery",
      "method": "POST"
    },
    "cancel": {
      "href": "/v2/invoices/98762/cancelation",
      "method": "POST"
    }
  },
  "id": "98762",
  "submitTimeUtc": "2024-08-02T19:24:06.184293960Z",
  "status": "CREATED",
  "processingInformation": {
    "requestPhone": false,
    "requestShipping": false
  },
  "invoiceInformation": {
    "invoiceNumber": "98762",
    "description": "Food",
    "dueDate": "2019-07-11",
    "allowPartialPayments": false,
    "paymentLink": "https://businesscenter.cybersource.com/ebc2/invoicing/payInvoice/NyvghJCpsrrZAjkvZNxelqUrI7iyOdLXFXWS8e5MLXyLYbifinsuYfBk6kaYo3co?version=v2.1",
    "deliveryMode": "None"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": 2623.64,
      "currency": "USD",
      "balanceAmount": 2623.64
    }
  }}
Request
12345678910111213141516171819202122232425262728293031
{"customerInformation": {
    "name": "Tanya Lee",
    "email": "tanya.lee@my-email.world"
  },
  "invoiceInformation": {
    "dueDate": "2019-07-11",
    "sendImmediately": false,
    "deliveryMode": "none"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "293.50",
      "currency": "USD"
    },
    "lineItems": [
      {
        "productSku": "P653727383",
        "productName": "First line item's name",
        "quantity": "20",
        "unitPrice": "12.05",
        "totalAmount": "241.00"
      },
      {
        "productSku": "P653727383",
        "productName": "First line item's name",
        "quantity": "10",
        "unitPrice": "5.25",
        "totalAmount": "52.50"
      }
    ]
  }}
Response to a Successful Request
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657
{"_links": {
    "self": {
      "href": "/v2/invoices/98764",
      "method": "GET"
    },
    "update": {
      "href": "/v2/invoices/98764",
      "method": "PUT"
    },
    "deliver": {
      "href": "/v2/invoices/98764/delivery",
      "method": "POST"
    },
    "cancel": {
      "href": "/v2/invoices/98764/cancelation",
      "method": "POST"
    }
  },
  "id": "98764",
  "submitTimeUtc": "2024-08-02T22:14:13.000671718Z",
  "status": "DRAFT",
  "customerInformation": {
    "name": "Tanya Lee",
    "email": "tanya.lee@my-email.world"
  },
  "processingInformation": {
    "requestPhone": false,
    "requestShipping": false
  },
  "invoiceInformation": {
    "invoiceNumber": "98764",
    "dueDate": "2019-07-11",
    "allowPartialPayments": false,
    "deliveryMode": "None"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": 293.5,
      "currency": "USD"
    },
    "lineItems": [
      {
        "productSku": "P653727383",
        "productName": "First line item's name",
        "unitPrice": 12.05,
        "quantity": 20,
        "totalAmount": 241
      },
      {
        "productSku": "P653727383",
        "productName": "First line item's name",
        "unitPrice": 5.25,
        "quantity": 10,
        "totalAmount": 52.5
      }
    ]
  }}