Vendor credits

A vendor credit is an adjustment on the amount that you owe a vendor.

In a vendor credit, you can add vendor credit line items to record details about a credit you want to apply for an individual good or service. In addition, you can apply vendor credits to payments.

See the /v3/vendor-credits API for more information about the complete list of vendor credit operations.

Create a vendor credit

In your POST /v3/vendor-credits request, set the required fields.

Field	Description
`vendorId`	BILL-generated ID of the vendor. The value begins with `009`.
`referenceNumber`	User-generated vendor credit number. This value can be in your chosen number scheme.
`creditDate`	Vendor credit issued date. This value is in the `yyyy-MM-dd` format.
`vendorCreditLineItems`	In the `vendorCreditLineItems` array, set the required information about the vendor credit line items.

See the /v3/vendor-credits APIfor more information about the other vendor credit fields you can set.

Sample request

In this cURL example, a vendor credit of $64.99 is created for the vendor (vendorId). A referenceNumber and creditDate is set for the vendor credit.

curl --request POST \
–-url 'https://gateway.stage.bill.com/connect/v3/vendor-credits' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "referenceNumber": "202502-vendorcredit",
  "creditDate": "2025-12-28",
  "vendorCreditLineItems": [
    {
      "description": "Classic extreme drum sticks",
      "amount": "14.99"
    },
    {
      "description": "Metal guitar picks (5-pack)",
      "amount": "50.00"
    }
  ],
  "description": "Happy Music Supplies Vendor Credit 20251228"
}'

Response

In the response, a BILL-generated vendor credit id is available. The value begins with vcr.

{
    "id": "{vendor_credit_id}",
    "vendorId": "{vendor_id}",
    "referenceNumber": "202502-vendorcredit",
    "creditDate": "2025-12-28",
    "description": "Happy Music Supplies Vendor Credit 20251228",
    "archived": false,
    "amount": 64.99,
    "appliedAmount": 0.00,
    "status": "NOT_APPLIED",
    "createdTime": "2025-12-26T19:41:29.127+00:00",
    "updatedTime": "2025-12-26T19:41:29.127+00:00",
    "vendorCreditLineItems": [
        {
            "id": "{vendorCreditLineItem_id01}",
            "description": "Classic extreme drum sticks",
            "amount": 14.99
        },
        {
            "id": "{vendorCreditLineItem_id02}",
            "description": "Metal guitar picks (5-pack)",
            "price": 50.00
        }
    ]
}

Apply a vendor credit to a payment

In your POST /v3/payments request, set the required fields.

Field	Description
`billId`	BILL-generated ID of the bill to be paid. This value begins with `00n`. If `createBill` is `true`, do not set `billId` in your payment request.
`processDate`	Bill payment processing date in the `yyyy-MM-dd` format. Funds are withdrawn from the sender's funding account on this date. If the funding account type is set as `WALLET`, `processDate` is required. For other funding account types, if `processDate` is not set, the date is automatically set as the next available payment date.
`fundingAccount`	Funding account information. - `type` (`BANK_ACCOUNT`, `CARD_ACCOUNT`, or `WALLET` (BILL balance)) - `id`: BILL-generated ID of the selected payment funding type. For the `WALLET` type, `id` is not required.
`amount`	Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.
`processingOptions`	Payment processing options. - Set `createBill` as `false` to create a vendor payment for an existing bill. - Set `createBill` as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.
`vendorCredits`	Vendor credits information. - `id`: BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`. - `amount`: Credit amount

❗️
Vendor credit updates after applying it to a payment
When a vendor credit is applied to a payment, there are three updates to note in the vendor credit response.

The appliedAmount is updated to show the total vendor credit amount that has been applied.

The status is updated to PARTIALLY_APPLIED or FULLY_APPLIED depending on the vendor credit amount.

The usage array lists the bills and payments that the vendor credit is applied to.

Sample request

In this cURL example, a vendor credit is applied to a payment of $228.99. The required vendorCredits fields are set for adding a $25.00 vendor credit. The payment amount in the request is $203.99 ($228.99 - $25.00).

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "billId": "{bill_id}",
  "processDate": "2025-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{bank_account_id}"
  },
  "amount": 203.99,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": false
  },
  "vendorCredits": {
  	"id": "{vendor_credit_id}",
    "amount": 25.00
  }
}'

Response

In the response, a BILL-generated payment id is available. The value begins with stp. The vendor credit information is available in billPayments.

{
  "id": "stp01ZZRCUFIQWHP6ldb",
  "vendorId": "{vendor_id}",
  "vendorName": "{vendor_name}",
  "billId": "{bill_id}",
  "billPayments": [
    {
      "id": "{bill_payment_id}",
      "billId": "{bill_id}",
      "amount": 203.99,
      "vendorCredits": {
      	"id": "{vendor_credit_id}",
        "amount": 25.00
      }
    }
  ],
  "description": "Inv #20251231",
  "processDate": "2025-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{bank_account_id}"
  },
  "amount": 203.99,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": false,
    "requestCheckDeliveryType": "STANDARD"
  },
  "transactionNumber": "EPKZLNTSTYSEUWVALISV",
  "confirmationNumber": "P24123101 - 0411839",
  "status": "SCHEDULED",
  "onlinePayment": true,
  "disbursementType": "ACH",
  "createdTime": "2025-12-30T23:56:52.127+00:00",
  "updatedTime": "2025-12-30T23:56:52.127+00:00",
  "createdBy": "{user_id}",
  "voidInfo": [],
  "singleStatus": "SCHEDULED"
}

See the /v3/vendor-credits API for more information about the complete list of vendor credit operations.

Create a vendor credit

Sample request

Response

Apply a vendor credit to a payment

❗️Vendor credit updates after applying it to a payment

Sample request

Response

❗️
Vendor credit updates after applying it to a payment