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.

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.

👍

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.

👍

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.

👍

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.