Bills
A bill represents an amount owed for goods and services provided by a vendor.
In the bill, you can add bill line items to record details about individual goods or services. In addition, you can add invoice information for associating the bill with an invoice.
Use POST /v3/bills
to create a bill. You can also use POST /v3/bills/bulk
to create multiple bills with one request. See the /v3/bills API for more information about the complete list of bill operations.
Creating a bill
In your POST /v3/bills
request, set the required fields.
Field | Description |
---|---|
vendorId | BILL-generated ID of the vendor you want to pay. This value begins with 009 . |
dueDate | Bill due date. This value is in the yyyy-MM-dd format. |
billLineItems | In the billLineItems array, set amount as the bill line item amount. |
invoiceNumber | Bill invoice number. This value can be your chosen number scheme or bill due date. |
invoiceDate | Bill invoice sent date. This value is in the yyyy-MM-dd format. |
See the /v3/bills API for more information about the other bill fields you can set.
Sample request
In this cURL example, a bill of $228.99
is created for the vendor (vendorId
). An invoice number and invoice sent date is added for the bill.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/bills' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
"vendorId": "{vendor_id}",
"dueDate": "2024-12-31",
"billLineItems": [{
"amount": 149.00,
"description": "USB audio interface"
},
{
"amount": 79.99,
"description": "Drum foot pedal"
}],
"invoice": {
"invoiceNumber": "202401",
"invoiceDate": "2024-12-31"
}
}'
Response
In the response, a BILL-generated bill id
is available. This value begins with 00n
. You can use this bill id
for other BILL operations.
{
"id": "{bill_id}",
"archived": false,
"vendorId": "{vendor_id}",
"amount": 228.99,
"dueDate": "2024-12-31",
"invoice": {
"invoiceNumber": "202401",
"invoiceDate": "2024-12-31"
},
"billLineItems": [
{
"id": "{billLineItem_id01}",
"amount": 149.00,
"description": "USB audio interface"
},
{
"id": "{billLineItem_id02}",
"amount": 79.99,
"description": "Drum foot pedal"
}
],
"createdTime": "2024-12-30T23:15:23.127+00:00",
"updatedTime": "2024-12-30T23:15:23.127+00:00"
}
If the bill is created for an international vendor (not US), there are three bill amount-related fields to note.
Field | Description |
---|---|
fundingAmount | Bill amount in USD. |
exchangeRate | Exchange rate for the bill amount in the international currency (not USD). The BILL exchange rate changes periodically and a different rate may apply at the time of payment. |
amount | Bill line item amount. This value is in the local currency. |
See the /v3/bills API for more information about the complete list of bill operations.
Creating multiple bills
You can use POST /v3/bills/bulk
to create multiple bills with one API request.
Bulk bill creation at BILL follows a set of rules.
- Successful response: In your bulk bill creation request, all your bills must be successfully created for a successful response. If any bill creation is not successful, the entire request fails and none of the bills in the request are created.
- You can create bills for multiple vendors: You can create bills for one vendor or for multiple vendors with one
POST /v3/bills/bulk
request.
See the /v3/bills/bulk API for more information.
Sample request
In this cURL example, two bills are created. The amount for the first bill is $149.00
and the amount for the second bill is $79.99
. Invoice numbers and invoice sent dates are added for each bill.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/bills/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '[
{
"vendorId": "{vendor_id}",
"description": "USB audio interface bill",
"dueDate": "2024-12-31",
"billLineItems": [
{
"amount": 149.00,
"description": "USB audio interface"
}
],
"invoice": {
"invoiceDate": "2024-12-31",
"invoiceNumber": "202412311"
}
},
{
"vendorId": "{vendor_id}",
"description": "Drum foot pedal bill",
"dueDate": "2024-12-31",
"billLineItems": [
{
"amount": 79.99,
"description": "Drum foot pedal"
}
],
"invoice": {
"invoiceDate": "2024-12-31",
"invoiceNumber": "202412312"
}
}
]'
Successful response
In this successful response, a BILL-generated payment id
is available for each created bill. The value begins with 00n
. You can use the bill id
values for other BILL operations.
[
{
"id": "{bill_id01}",
"archived": false,
"vendorId": "{vendor_id}",
"amount": 149.00,
"description": "USB audio interface bill",
"dueDate": "2024-12-31",
"invoice": {
"invoiceNumber": "202412311",
"invoiceDate": "2024-12-31"
},
"billLineItems": [
{
"id": "{billLineItem_id01}",
"amount": 149.00,
"description": "USB audio interface"
}
],
"createdTime": "2024-12-30T23:15:23.127+00:00",
"updatedTime": "2024-12-30T23:15:23.127+00:00"
},
{
"id": "{bill_id02}",
"archived": false,
"vendorId": "{vendor_id}",
"amount": 79.99,
"description": "Drum foot pedal bill",
"dueDate": "2024-12-31",
"invoice": {
"invoiceNumber": "202412312",
"invoiceDate": "2024-12-31"
},
"billLineItems": [
{
"id": "{billLineItem_id02}",
"amount": 79.99,
"description": "Drum foot pedal"
}
],
"createdTime": "2024-12-30T23:15:27.127+00:00",
"updatedTime": "2024-12-30T23:15:27.127+00:00"
}
]
Error response
In this error response for the above POST /v3/bills/bulk
sample request, since there is an error with creating the first bill, the entire request fails and none of the bills in the request are created. In this example, the vendorId
for the first bill in the request could not be found.
[
{
"timestamp": "2024-12-30T23:15:27.000+00:00",
"code": "BDC_1205",
"severity": "ERROR",
"category": "DOWNSTREAM",
"message": "No data found for object with id {vendor_Id}."
},
{
"timestamp": "2024-12-30T23:15:27.000+00:00",
"code": "BDC_1246",
"severity": "ERROR",
"category": "DOWNSTREAM",
"message": "Changes were rollback due to other failures within this transaction."
}
]
See the /v3/bills/bulk API for more information.
Updated 2 months ago