v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB

vendor-credits

Replace a vendor credit

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

You can use the PUT operation to add, remove, or replace the number of line items in a vendor credit. 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 vendor credit.
When you omit an existing line item id, the line item is removed from the vendor credit.

put/v3/vendor-credits/{vendorCreditId}

Path parameters

vendorCreditIdstring required

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

Example:{{vendor_credit_id}}

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.

referenceNumberstring required

User-generated vendor credit number. This value can be in your chosen number scheme.

creditDatestring date required

Vendor credit issued date. This value is in the yyyy-MM-dd format.

descriptionstring

Vendor credit description

applyToChartOfAccountIdstring

BILL-generated ID of the chart of accounts used when the vendor credit is applied to a bill payment. The value begins with 0ca.

applyToBankAccountIdstring

BILL-generated ID of the bank account used when the vendor credit is applied to a bill payment. The value begins with bac.

Note: You can set only one of applyToChartOfAccountId or applyToBankAccountId.

Example request

{
  "vendorId": "{{vendor_id}}",
  "referenceNumber": "202602-vendorcredit",
  "creditDate": "2026-12-28",
  "description": "Happy Vendor Credit (line item added)",
  "vendorCreditLineItems": [
    {
      "description": "Premium drummer gloves",
      "amount": 29.99
    },
    {
      "id": "{{vendor_credit_line_item_id01}}",
      "description": "Classic extreme drum sticks",
      "amount": 19.99
    },
    {
      "id": "{{vendor_credit_line_item_id02}}",
      "description": "Metal guitar picks (5-pack)",
      "amount": 50
    }
  ]
}

Response

Replace a vendor credit response

idstring

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

vendorIdstring

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

referenceNumberstring

User-generated vendor credit number. This value can be in your chosen number scheme.

creditDatestring date

Vendor credit issued date. This value is in the yyyy-MM-dd format.

descriptionstring

Vendor credit description

archivedboolean

Set as true if the vendor credit is archived

applyToChartOfAccountIdstring

BILL-generated ID of the chart of accounts used when the vendor credit is applied to a bill payment. The value begins with 0ca.

applyToBankAccountIdstring

BILL-generated ID of the bank account used when the vendor credit is applied to a bill payment. The value begins with bac.

Note: You can set only one of applyToChartOfAccountId or applyToBankAccountId.

amountnumber

Vendor credit amount

appliedAmountnumber

Vendor credit amount applied to invoices

status'FULLY_APPLIED' | 'NOT_APPLIED' | 'PARTIALLY_APPLIED' | 'IN_PROCESS' | 'UNDEFINED'

Vendor credit status.

createdTimestring date-time

Vendor credit created time

updatedTimestring date-time

Vendor credit updated time