Guides
System Status

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 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. You can also use the PUT operation.

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.

Vendor credit updates after applying it to a bill
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.

Bill updates after a vendor credit is applied
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.

Unapply vendor credit from a bill

In your PUT /v3/bills/{billId} request, set all the bill details and remove the existing vendor credits information.

Sample request

In this cURL example, a vendor credit is applied to an existing bill (billId). To unapply the vendor credit from the bill, the vendor credit information is removed from the PUT request.

curl --request PUT \
–-url 'https://gateway.stage.bill.com/connect/v3/bills/{billId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "dueDate": "2025-12-31",
  "billLineItems": [
    {
      "id": "{bill_line_item_id}",
      "amount": 79.99,
      "description": "Drum foot pedal"
    }
  ],
  "invoice": {
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-31"
  },
  "vendorCredits": [
    {
      "id": "{vendor_credit_id}",
      "amount": 10.00
    }
  ]
}'

curl --request PUT \
–-url 'https://gateway.stage.bill.com/connect/v3/bills/{billId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "dueDate": "2025-12-31",
  "billLineItems": [
    {
      "id": "{bill_line_item_id}",
      "amount": 79.99,
      "description": "Drum foot pedal"
    }
  ],
  "invoice": {
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-31"
  }
}'

Apply vendor credit to a payment

❗️

A vendor credit cannot be unapplied from a payment

After you apply a vendor credit to a payment, the vendor credit cannot be unapplied from the payment. You can unapply a vendor credit from a bill before the bill is paid.

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.

Vendor credit updates after applying it to a payment
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

❗️

A vendor credit cannot be unapplied from a payment

After you apply a vendor credit to a payment, the vendor credit cannot be unapplied from the payment. You can unapply a vendor credit from a bill before the bill is paid.

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.

Vendor credit updates after applying it to a payment
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.

Updated 1 day ago