On This Page

{#jumplink-list}  
[Markdown](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-create-draft-intro.md)  
Filter  
FILTER BY TAG

Create a Draft Invoice {#invoicing-services-create-draft-intro}
===============================================================

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`. The created invoice is then shareable with the customer.

**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](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-line-items.md "").

**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](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-create-draft-intro.md "").

    To create a new invoice that is **not** immediately sent in an email to the customer, see [Create an Invoice without Sending it](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-create-intro.md "").

    To create **and send** a new invoice at the same time, see [Create and Send an Invoice Immediately](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-create-send-intro.md "").

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`

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](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-send-intro.md "").

**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](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-update-intro.md "").

**Cancel an Invoice**
:
To cancel a drafted invoice, send the a cancel invoice request. For more information, see [Cancel an Invoice](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-cancel-intro.md "").

**Get Invoice Details**
:
To retrieve a drafted invoice's details, send a get invoice details request. For more information, see [Get Invoice Details](/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/invoicing-services-intro/invoicing-services-get-details-intro.md "").

Required Fields for Drafting an Invoice {#invoicing-services-create-draft-req-fields}
=====================================================================================

This section lists the required fields necessary to create these types of invoices:
* 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`.

[orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "")
:

[orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "")
:

Required Fields for Drafting an Email Invoice {#invoicing-services-create-draft-req-fields_customer-fields}
-----------------------------------------------------------------------------------------------------------

customerInformation.email
:

customerInformation.name
:

invoiceInformation.deliveryMode
:
Set to `email`.

invoiceInformation.dueDate
:

invoiceInformation.sendImmediately
:
Set to `false`.

[orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "")
:

[orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "")
:

Required Fields for Drafting an Invoice with Line Items {#invoicing-services-create-draft-req-fields_line-item-fields}
----------------------------------------------------------------------------------------------------------------------

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.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "")
:

[orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "")
:

[orderInformation.lineItems\[\].productName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-product-name.md "")
:

orderInformation.lineItems\[\].productSku
:

[orderInformation.lineItems\[\].quantity](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-quantity.md "")
:

[orderInformation.lineItems\[\].totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-total-amount.md "")
:

[orderInformation.lineItems\[\].unitPrice](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-unit-price.md "")
:

Optional Fields for Invoice Creation {#invoicing-services-create-opt-fields}
============================================================================

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

[clientReferenceInformation.partner.developerId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-partner-developer-id.md "")
:
Set to your developer ID.

[clientReferenceInformation.partner.solutionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-partner-solution-id.md "")
:
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 {#invoicing-services-opt-details-tax-fields}
====================================================================================

You can include discounts and taxes to either the total billed amount or to billed line items in an invoice.

> 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.discountAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-discount-amount.md "")
:

orderInformation.amountDetails.discountPercent
:

Discount Fields for Line Items
------------------------------

[orderInformation.lineItems\[\].discountAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-discount-amount.md "")
:

[orderInformation.lineItems\[\].discountRate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-discount-rate.md "")
:

Tax Fields for the Invoice Total
--------------------------------

orderInformation.amountDetails.taxDetails.amount
:

orderInformation.amountDetails.taxDetails.rate
:

orderInformation.amountDetails.taxDetails.type
:

Tax Fields for Line Items
-------------------------

[orderInformation.lineItems\[\].taxAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-tax-amount-request.md "")
:

[orderInformation.lineItems\[\].taxRate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-tax-rate.md "")
:

Example: Drafting an Invoice {#invoicing-services-create-draft-done-ex-rest}
============================================================================

Request

```
{
  "invoiceInformation": {
    "description": "Food",
    "dueDate": "2019-07-11",
    "sendImmediately": false,
    "deliveryMode": "none"
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "2623.64",
      "currency": "USD"
    }
  }
}
```

Response to a Successful Request

```keyword
{
  "_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

```
{
  "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

```
{
  "_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
      }
    ]
  }
}
```

REST Interactive Example: Create an Invoice Draft {#invoicing-services-create-draft-ex-live}
============================================================================================

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

#### Figure: {#invoicing-services-create-draft-ex-live_cybs-create-invoice}

Interactive Code [![Image and link to the interactive code example for creating a new
invoice.](/content/dam/documentation/cybs/en-us/topics/payments-processing/payment-services/invoicing/images/invoicing-services-create.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md#invoicing_invoices_create-a-new-invoice "")  
RELATED TO THIS PAGE

* [Getting Started with REST](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md)
* [Response Codes](https://developer.cybersource.com/api/reference/response-codes.md)
* [API Field Reference Guide](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md)
* [API Reference Sandbox](https://developer.cybersource.com/api-reference-assets/index.md#static-home-section)
* [Business Center Test](https://businesscentertest.cybersource.com/ebc2/)
* [Business Center Production](https://businesscenter.cybersource.com/ebc2/)
* [Customer Support](https://support.visaacceptance.com/)