BIbill
bills

Create a bill

Changed on

Create a new bill.

See Bills in the Guides section for more information, sample requests, and responses.

post/v3/bills

Request

  • Base URL
    https://gateway.stage.bill.com/connect
  • URL
    https://gateway.stage.bill.com/connect/v3/bills
  • Auth
    none declared

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

vendorIdstring required

BILL-generated ID of the vendor. The value begins with 009.

descriptionstring

Bill description

dueDatestring date required

Bill due date. The value is in the yyyy-MM-dd format.

paymentTermIdstring
payFromChartOfAccountIdstring

BILL-generated ID of the chart of accounts for the bill payment. The value begins with 0ca.

purchaseOrderNumberstring

Purchase order number linked with the bill

billApprovalsboolean

Set as true for BILL to add approvals information in the response.

When you have approval policies set up for bills and a bill matches a policy, you see an additional approvers array of objects in the response. The array shows the list of individual users and/or user groups assigned as bill approvers. In addition, the array provides information about the status of the bill in the current approval flow.

Note: When you set billApprovals as true, you must set the field as true if you want to update the bill (PATCH /v3/bills/{billId}) or replace the bill (PUT /v3/bills/{billId}).

allowDuplicateInvoiceNumberboolean

Set as false to reject the request when the bill's invoice.invoiceNumber duplicates an existing invoice number for the vendor. Defaults to true, which allows duplicate invoice numbers.

Example request

{
  "vendorId": "{{vendor_id}}",
  "dueDate": "2026-12-31",
  "billLineItems": [
    {
      "amount": 149,
      "description": "USB audio interface"
    },
    {
      "amount": 79.99,
      "description": "Drum foot pedal"
    }
  ],
  "invoice": {
    "invoiceNumber": "202601",
    "invoiceDate": "2026-12-31"
  }
}

Response

Create a bill response

idstring required

BILL-generated ID of the bill. The value begins with 00n.

archivedboolean required

Set as true if the bill is archived

vendorIdstring required

BILL-generated ID of the vendor. The value begins with 009.

fundingAmountnumber

Bill total amount. This value is in USD.

amountnumber

Bill total amount. For a bill in an international currency (not USD), this value is in the local currency.

paidAmountnumber

Bill paid amount. This value is the sum of all cleared payments and any credit amount applied to the bill.

dueAmountnumber

Bill due amount. The value is calculated by subtracting any applied credits (creditAmount), scheduled payment (scheduledAmount), and cleared payment from the bill amount.

scheduledAmountnumber

Bill scheduled amount. The value is set as the vendor payment amount that is pending clearance.

creditAmountnumber

Credit amount applied to the bill

exchangeRatenumber

Exchange rate for the bill amount in an international currency (not USD).

The BILL exchange rate changes periodically and a different rate may apply at the time of payment.

descriptionstring

Bill description

dueDatestring date

Bill due date. The value is in the yyyy-MM-dd format.

paymentTermIdstring
payFromChartOfAccountIdstring

BILL-generated ID of the chart of accounts for the bill payment. The value begins with 0ca.

paymentStatus'PAID' | 'UNPAID' | 'PARTIALLY_PAID' | 'SCHEDULED' | 'IN_PROCESS' | 'UNDEFINED'

Bill payment status.

approvalStatus'UNASSIGNED' | 'ASSIGNED' | 'APPROVED' | 'APPROVING' | 'DENIED' | 'UNDEFINED'

Bill approval status.

createdBystring

BILL-generated ID of the user that created the bill. The value begins with 006.

createdTimestring date-time

Created date and time

updatedTimestring date-time

Updated date and time

purchaseOrderNumberstring

Purchase order number linked with the bill

recurringBillIdstring

BILL-generated ID of the recurring bill that generated this bill. The value begins with btp.

Changes

  • 54edddceb0a5Revision changes
    • breaking

      the request property ///// became required

    • breaking

      the request property ///// became required

    • breaking

      the ///// request property's minLength was increased from 0 to 1

    • warning

      the ///// request property's maxLength was set to 100

    • info

      added the new optional request property

    • info

      added the new optional request property /////

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property to the response with the status

    • info

      the response property ///// became required for the status

    • info

      the response property ///// became required for the status