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.

FieldDescription
vendorIdBILL-generated ID of the vendor. The value begins with 009.
referenceNumberUser-generated vendor credit number. This value can be in your chosen number scheme.
creditDateVendor credit issued date. This value is in the yyyy-MM-dd format.
vendorCreditLineItemsIn 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 vendor credit to a bill

In your PATCH /v3/bills/{billId} request, set the required fields.

FieldDescription
billIdBILL-generated ID of the bill. The value begins with 00n.
vendorCreditsVendor 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 bill

When a vendor credit is applied to a bill, 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 an existing bill (billId).

curl --request PATCH \
–-url 'https://gateway.stage.bill.com/connect/v3/bills/{billId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorCredits": [
    {
      "id": "{vendor_credit_id}",
      "amount": 10.00
    }
  ]
}'

Response

In the response, the bill is updated based on the applied vendorCredits amount.

  • creditAmount is set as the credit amount applied to the bill.
  • dueAmount is calculated by subtracting any applied credits (creditAmount), scheduled payment (scheduledAmount), and cleared payment from totalAmount.
  • The bill paymentStatus is set as PARTIALLY_PAID or PAID depending on the bill total amount.

Apply vendor credit to a payment

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

FieldDescription
billIdBILL-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.
processDateBill 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.
fundingAccountFunding 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.
amountPayment amount information. For a payment in an international currency (not USD), this value is in the local currency.
processingOptionsPayment 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.
vendorCreditsVendor 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"
}

Apply vendor credit to a bulk payment

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

FieldDescription
fundingAccountFunding 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.
billIdBILL-generated ID of the bill to be paid. This value begins with 00n.
amountPayment amount
vendorCreditsVendor 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 bulk payment is created with two bills that belong to different vendors. The billId is associated with each payment. 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/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{bank_account_id}"
  },
  "payments": [
    {
      "billId": "{bill_id01}",
      "amount": 203.99,
      "vendorCredits": {
      	"id": "{vendor_credit_id}",
        "amount": 25.00
      }
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Response

In the successful response, a different BILL-generated payment id is available for each payment made to each vendor. Each id value begin with stp. The vendor credit information is available in billPayments.

See Create a bulk payment to see more sample requests and responses for creating bulk payments.