System status

Invoices

An invoice represents an amount that you are owed by a customer for goods and services that your organization provides.

In the invoice, you can add invoice line items to record details about individual goods or services. In addition, you associate the invoice to an existing customer or create a new customer with the invoice. See the /v3/invoices API for more information about the complete list of invoice operations.

Creating an invoice

In your POST /v3/invoices, set the required fields.

FieldDescription
idBILL-generated ID of the customer you want to associate the invoice to. This value begins with 0cu.

To create a new customer with the invoice, set name and email instead of a customer id.
lineItemsIn the lineItems array, set quantity as the invoice line item quantity.

You can add more line item details with description and price.

See the /v3/invoices API for more information about the other invoice fields you can set.

Sample request

In this cURL example, an invoice of $79.98 is created for the customer (id). An invoice number and invoice due date is added. In addition, sendEmail is set as true for sending an email to the customer when the invoice is created.

curl --request POST \
–-url 'https://gateway.stage.bill.com/connect/v3/invoices' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "customer": {
    "id": "{customer_id}"
  },
  "lineItems": [
    {
      "quantity": 2,
      "description": "Classic extreme drum sticks",
      "price": "14.99"
    },
    {
      "quantity": "1",
      "description": "Metal guitar picks (5-pack)",
      "price": "50.00"
    }
  ],
  "invoiceNumber": "202402",
  "dueDate": "2024-12-31",
  "processingOptions": {
    "sendEmail": true
  }
}'

Response

In the response, a BILL-generated invoice id is available. The value begins with 00e. You can use this invoice id for other BILL operations.

{
  "id": "{invoice_id}",
  "archived": false,
  "invoiceNumber": "202402",
  "invoiceDate": "2024-12-30",
  "dueDate": "2024-12-31",
  "customerId": "{customer_id}",
  "totalAmount": 79.98,
  "status": "OPEN",
  "createdTime": "2024-12-30T19:41:29.000Z",
  "updatedTime": "2024-12-30T19:41:29.000Z",
  "lineItems": [
    {
      "id": "00f01KTXKOOQEPJH6ct2",
      "description": "Classic extreme drum sticks",
      "price": 14.99,
      "quantity": 2
    },
    {
      "id": "00f01SVIRXQQUXJS6ct3",
      "description": "Metal guitar picks (5-pack)",
      "price": 50.00,
      "quantity": 1
    }
  ]
}

📘

NOTE

For an international customer, exchangeRate is an additional field in the response.

Sending an invoice payment reminder to a customer

Use POST /v3/invoices/{invoiceId}/email to send an invoice to a customer email address. You can send the invoice to multiple email addresses.

See Send an invoice in the API reference for more information.

Sample request

In this cURL example, a request is sent to email an invoice to a customer. The customer email address is added in the request.

curl --request POST \
–-url 'https://gateway.stage.bill.com/connect/v3/invoices/{invoiceId}/email' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "replyTo": {
    "userId": "{user_id}"
  },
  "recipient": {
    "to": [
      "[email protected]"
    ]
  }
}'

See the /v3/invoices API for more information about the complete list of invoice operations.

Updated 9 days ago