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.

Create an invoice

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

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}"
  },
  "invoiceLineItems": [
    {
      "quantity": 2,
      "description": "Classic extreme drum sticks",
      "price": 14.99
    },
    {
      "quantity": 1,
      "description": "Metal guitar picks (5-pack)",
      "price": 50.00
    }
  ],
  "invoiceNumber": "202502",
  "dueDate": "2025-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. Since invoiceDate is not set in the request, this value is set as the date when the invoice is created.

{
  "id": "{invoice_id}",
  "archived": false,
  "invoiceNumber": "202502",
  "invoiceDate": "2025-12-30",
  "dueDate": "2025-12-31",
  "customerId": "{customer_id}",
  "totalAmount": 79.98,
  "status": "OPEN",
  "createdTime": "2025-12-30T19:41:29.127+00:00",
  "updatedTime": "2025-12-30T19:41:29.127+00:00",
  "invoiceLineItems": [
    {
      "id": "{invoiceLineItem_id01}",
      "description": "Classic extreme drum sticks",
      "price": 14.99,
      "quantity": 2
    },
    {
      "id": "{invoiceLineItem_id02}",
      "description": "Metal guitar picks (5-pack)",
      "price": 50.00,
      "quantity": 1
    }
  ],
  "payments": []
}

👍

exchangeRate is available for international customers

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

Send 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.

Get invoice payment link

Use POST /v3/invoices/{invoiceId}/payment-link to get an invoice payment link. When you generate an invoice for a customer, you send an invoice payment link to the customer. With this link, the customer can complete the invoice payment without the need to set up a BILL account.

In your POST /v3/invoices/{invoiceId}/payment-link, set the required fields.

See the /v3/invoices/{invoiceId}/payment-link API for more information about the other fields you can set.

Sample request

In this cURL example, a request is sent to get an invoice payment link for a customer.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/invoices/{invoiceId}/payment-link' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "customerId": "{customer_id}",
  "email": "{customer_email_address}"
}'

Response

In the response, a BILL-generated invoice payment link is available. Send this payment link to your customer.

{
  "paymentLink": "{invoice_payment_link}"
}

Test with invoice payment link

You can test with the invoice payment link and confirm that it works as expected. When you navigate to the payment link, the customer can pay with a bank account or card account.

👍

Your BILL account must have the invoice payment method options enabled

When a payment method is enabled, it is available to the customer as a payment method with the invoice payment link.

1. Sign in to the BILL sandbox web app. Use your developer account email address and password.
2. Click Settings in your BILL account.
3. Click Receivables settings > Online payments.
4. Enable the Credit or debit card and ePayment methods as required.

Test card account information

Use the provided test card account information to test with the customer payment flow.

Test bank account information

Use the provided test bank account information to test with the customer payment flow

See the /v3/invoices/{invoiceId}/payment-link API for more information.