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 vendor credit to a bill
In your PATCH /v3/bills/{billId}
request, set the required fields.
Field | Description |
---|---|
billId | BILL-generated ID of the bill. The value begins with 00n . |
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 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 toPARTIALLY_APPLIED
orFULLY_APPLIED
depending on the vendor creditamount
.- 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 fromtotalAmount
.- The bill
paymentStatus
is set asPARTIALLY_PAID
orPAID
depending on the bill totalamount
.
Apply 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 toPARTIALLY_APPLIED
orFULLY_APPLIED
depending on the vendor creditamount
.- 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.
Field | Description |
---|---|
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. |
billId | BILL-generated ID of the bill to be paid. This value begins with 00n . |
amount | Payment amount |
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 toPARTIALLY_APPLIED
orFULLY_APPLIED
depending on the vendor creditamount
.- 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 3 days ago