Replace a bill

Update the number of line items in a bill. You can also update other bill details.

You can use the PUT operation to add, remove, or replace the number of line items in a bill. A set of rules apply with the PUT operation.

When you add a new line item, a new line item id is generated in the bill.
When you omit an existing line item id, the line item is removed from the bill.

billIdstring required

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

Example:{{bill_id}}

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 with PATCH /v3/bills/{billId}.

Example request

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

Response

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

Bill payment status.

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