---
updatedAt: 2026-04-21T17:39:49.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# Bulk create vendor credits

Bulk create vendor credit objects. The maximum number of objects you can set in a bulk operation is 100.

### What is a vendor credit?
A vendor credit is an adjustment on the amount that you owe a vendor. Vendor credits do not have due dates.

You can create a vendor credit with `/v2/Crud/Create/VendorCredit.json`. In the vendor credit, add vendor credit line items to record credit details at a granular level. In addition, you can associate line items to accounts tracking objects, such as item or chart of accounts.

You can apply a vendor credit to a bill with `/v2/PayBills.json` or `/v2/RecordAPPayment.json`.

Other vendor credit features: 
* When a vendor credit requires approval, you can add vendor credit approvers with the BILL web app.
* You can reduce the total bill amount with a bill credit (with the BILL web app) or vendor credit (`/VendorCredit.json`). Total bill amount, bill credits, vendor credits, and any remaining bill amount paid or recorded is available with `/v2/Crud/Read/SentPay.json`.
* The `exchangeRate` is a required additional field for creating a vendor credit for an international vendor (a vendor outside the US). In addition, each vendor credit line item `amount` is in the foreign currency. Retrieve the current exchange rate with `/v2/GetDynamicExchangeRateQuote.json`.

**Note**: You must set `exchangeRate` when creating a bill for an international vendor even if the BILL foreign exchange rate changes at the time of bill payment.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "AP | Vendor transactions",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ]
  },
  "paths": {
    "/Bulk/Crud/Create/VendorCredit.json": {
      "post": {
        "summary": "Bulk create vendor credits",
        "operationId": "ap-vendortransactions-bulkcreatevendorcredit",
        "description": "Bulk create vendor credit objects. The maximum number of objects you can set in a bulk operation is 100.\n\n### What is a vendor credit?\nA vendor credit is an adjustment on the amount that you owe a vendor. Vendor credits do not have due dates.\n\nYou can create a vendor credit with `/v2/Crud/Create/VendorCredit.json`. In the vendor credit, add vendor credit line items to record credit details at a granular level. In addition, you can associate line items to accounts tracking objects, such as item or chart of accounts.\n\nYou can apply a vendor credit to a bill with `/v2/PayBills.json` or `/v2/RecordAPPayment.json`.\n\nOther vendor credit features: \n* When a vendor credit requires approval, you can add vendor credit approvers with the BILL web app.\n* You can reduce the total bill amount with a bill credit (with the BILL web app) or vendor credit (`/VendorCredit.json`). Total bill amount, bill credits, vendor credits, and any remaining bill amount paid or recorded is available with `/v2/Crud/Read/SentPay.json`.\n* The `exchangeRate` is a required additional field for creating a vendor credit for an international vendor (a vendor outside the US). In addition, each vendor credit line item `amount` is in the foreign currency. Retrieve the current exchange rate with `/v2/GetDynamicExchangeRateQuote.json`.\n\n**Note**: You must set `exchangeRate` when creating a bill for an international vendor even if the BILL foreign exchange rate changes at the time of bill payment.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkCreateVendorCreditResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](ref:auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/BulkCreateVendorCreditRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Vendor credits"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "CreateVendorCreditRequest": {
        "type": "object",
        "required": [
          "obj"
        ],
        "properties": {
          "obj": {
            "type": "object",
            "required": [
              "entity",
              "vendorId",
              "refNumber",
              "creditDate",
              "vendorCreditLineItems"
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `VendorCredit`.",
                "default": "VendorCredit"
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "vendorId": {
                "type": "string",
                "description": "BILL-generated ID of the vendor. The value begins with `009`."
              },
              "refNumber": {
                "type": "string",
                "description": "Vendor credit reference number. This value is usually provided by the vendor on their credit document."
              },
              "creditDate": {
                "type": "string",
                "description": "Date when the vendor credit is issued. This value is usually provided by the vendor on their credit document."
              },
              "glPostingDate": {
                "type": "string",
                "description": "Bill date in your organization’s general ledger in your choice of accounting software. The value is in the YYYY-MM-DD format."
              },
              "exchangeRate": {
                "type": "number",
                "description": "Exchange rate for creating a vendor credit for an international vendor. This value is required during bill creation and payments to international vendors."
              },
              "description": {
                "type": "string",
                "description": "Vendor credit description"
              },
              "poNumber": {
                "type": "string",
                "description": "Purchase order number associated with the vendor credit"
              },
              "applyToBankAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the bank account associated with the vendor credit. This field is available only for select BILL partners."
              },
              "applyToChartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts associated with the vendor credit. This is an accounts tracking object. This field is available only for specific BILL partners."
              },
              "vendorCreditLineItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "entity",
                    "amount"
                  ],
                  "properties": {
                    "entity": {
                      "type": "string",
                      "description": "Object type. Set as `VendorCreditLineItem`.",
                      "default": "VendorCreditLineItem"
                    },
                    "amount": {
                      "type": "number",
                      "description": "Vendor credit line item total amount"
                    },
                    "chartOfAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the chart of accounts associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "departmentId": {
                      "type": "string",
                      "description": "BILL-generated ID of the department associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "locationId": {
                      "type": "string",
                      "description": "BILL-generated ID of the location associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "BILL-generated ID of the job associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "customerId": {
                      "type": "string",
                      "description": "BILL-generated ID of the customer associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "jobBillable": {
                      "type": "boolean",
                      "description": "Set as `true` if the job associated with the vendor credit line item is billable"
                    },
                    "description": {
                      "type": "string",
                      "description": "Line item description"
                    },
                    "lineType": {
                      "type": "string",
                      "description": "Bill line item type.\n* `1`: Expense (if the price is not associated with an item)\n* `2`: Item"
                    },
                    "itemId": {
                      "type": "string",
                      "description": "BILL-generated ID of the item associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "quantity": {
                      "type": "number",
                      "description": "Quantity of items issued as a credit. Use this field when `lineType` is `2` (Item)."
                    },
                    "unitPrice": {
                      "type": "number",
                      "description": "Unit price of the items that have been credited. Use this field when `lineType` is `2` (Item)."
                    },
                    "employeeId": {
                      "type": "string",
                      "description": "BILL-generated ID of the employee associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "actgClassId": {
                      "type": "string",
                      "description": "BILL-generated ID of the accounting class associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "lineOrder": {
                      "type": "number",
                      "description": "Vendor credit line item order"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CreateVendorCreditResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `VendorCredit`."
              },
              "id": {
                "type": "string",
                "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`."
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "vendorId": {
                "type": "string",
                "description": "BILL-generated ID of the vendor. The value begins with `009`."
              },
              "refNumber": {
                "type": "string",
                "description": "Vendor credit reference number. This value is usually provided by the vendor on their credit document."
              },
              "approvalStatus": {
                "type": "string",
                "description": "Bill approval status.\n* `0`: Unassigned\n* `1`: Assigned\n* `3`: Approved\n* `4`: Approving\n* `5`: Denied"
              },
              "creditDate": {
                "type": "string",
                "description": "Date when the vendor credit is issued. This value is usually provided by the vendor on their credit document."
              },
              "glPostingDate": {
                "type": "string",
                "description": "Vendor credit date in your organization’s general ledger in your choice of accounting software. The value is in the YYYY-MM-DD format."
              },
              "amount": {
                "type": "number",
                "description": "Vendor credit total amount"
              },
              "localAmount": {
                "type": "number",
                "description": "Total vendor credit amount in local currency"
              },
              "exchangeRate": {
                "type": "number",
                "description": "Exchange rate for creating a vendor credit for an international vendor. This value is required during vendor credit creation and payments to international vendors."
              },
              "appliedAmount": {
                "type": "number",
                "description": "Total vendor credit amount applied"
              },
              "creditStatus": {
                "type": "string",
                "description": "vendor credit status.\n* `0`: Fully applied\n* `1`: Not applied\n* `2`: Partially applied"
              },
              "description": {
                "type": "string",
                "description": "Vendor credit description"
              },
              "createdTime": {
                "type": "string",
                "description": "Created date and time"
              },
              "updatedTime": {
                "type": "string",
                "description": "Updated date and time"
              },
              "poNumber": {
                "type": "string",
                "description": "Purchase order number associated with the vendor credit"
              },
              "applyToBankAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the bank account associated with the vendor credit. This field is available only for select BILL partners."
              },
              "applyToChartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts associated with the vendor credit. This is an accounts tracking object. This field is available only for select BILL partners."
              },
              "vendorCreditLineItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "entity": {
                      "type": "string",
                      "description": "Object type. Set as `VendorCreditLineItem`."
                    },
                    "id": {
                      "type": "string",
                      "description": "BILL-generated ID of the vendor credit line item. The value begins with `vci`."
                    },
                    "vendorCreditId": {
                      "type": "string",
                      "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`."
                    },
                    "amount": {
                      "type": "number",
                      "description": "Vendor credit line item amount"
                    },
                    "chartOfAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the chart of accounts associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "departmentId": {
                      "type": "string",
                      "description": "BILL-generated ID of the department associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "locationId": {
                      "type": "string",
                      "description": "BILL-generated ID of the location associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "BILL-generated ID of the job associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "customerId": {
                      "type": "string",
                      "description": "BILL-generated ID of the customer associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "jobBillable": {
                      "type": "boolean",
                      "description": "Set as `true` if the job associated with the vendor credit line item is billable"
                    },
                    "description": {
                      "type": "string",
                      "description": "Line item description"
                    },
                    "createdTime": {
                      "type": "string",
                      "description": "Created date and time"
                    },
                    "updatedTime": {
                      "type": "string",
                      "description": "Updated date and time"
                    },
                    "lineType": {
                      "type": "string",
                      "description": "Bill line item type.\n* `1`: Expense (if the price is not associated with an item)\n* `2`: Item"
                    },
                    "itemId": {
                      "type": "string",
                      "description": "BILL-generated ID of the item associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "quantity": {
                      "type": "number",
                      "description": "Quantity of items issued as a credit. Use this field when `lineType` is `2` (Item)."
                    },
                    "unitPrice": {
                      "type": "number",
                      "description": "Unit price of the items that have been credited. Use this field when `lineType` is `2` (Item)."
                    },
                    "employeeId": {
                      "type": "string",
                      "description": "BILL-generated ID of the employee associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "actgClassId": {
                      "type": "string",
                      "description": "BILL-generated ID of the accounting class associated with the vendor credit line item. This is an accounts tracking object."
                    },
                    "lineOrder": {
                      "type": "number",
                      "description": "Vendor credit line item order"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "BulkCreateVendorCreditRequest": {
        "type": "object",
        "required": [
          "bulk"
        ],
        "properties": {
          "bulk": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateVendorCreditRequest"
            }
          }
        }
      },
      "BulkCreateVendorCreditResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "bulk": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateVendorCreditResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}
```