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.
Field | Description |
---|---|
id | BILL-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 . |
lineItems | In 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. 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": "202402",
"invoiceDate": "2024-12-30",
"dueDate": "2024-12-31",
"customerId": "{customer_id}",
"totalAmount": 79.98,
"status": "OPEN",
"createdTime": "2024-12-30T19:41:29.127+00:00",
"updatedTime": "2024-12-30T19:41:29.127+00:00",
"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 15 days ago