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}",
  "dueDate": "2024-12-31",
  "invoice": {
    "invoiceNumber": "202401",
    "invoiceDate": "2024-12-31"
  },
  "billLineItems": [
    {
      "id": "{billLineItem_id01}",
      "amount": 149,
      "description": "USB audio interface"
    },
    {
      "id": "{billLineItem_id02}",
      "amount": 79.99,
      "description": "Drum foot pedal"
    }
  ],
  "createdTime": "2024-12-30T23:15:23.000Z",
  "updatedTime": "2024-12-30T23:15:23.000Z"
}

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}",
    "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.000Z",
    "updatedTime": "2024-12-30T23:15:23.000Z"
  },
  {
    "id": "{bill_id02}",
    "archived": false,
    "vendorId": "{vendor_id}",
    "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.000Z",
    "updatedTime": "2024-12-30T23:15:27.000Z"
  }
]

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.