---
updatedAt: 2026-06-29T20:33:19.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Replace a vendor credit

Update the number of line items in a vendor credit. You can also update other vendor credit details.

You can use the PUT operation to add, remove, or replace the number of line items in a vendor credit. A set of rules apply with the PUT operation.
* When you add a new line item, a new line item `id` is generated in the vendor credit.
* When you omit an existing line item `id`, the line item is removed from the vendor credit.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BILL v3 API",
    "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://gateway.stage.bill.com/connect",
      "description": "sandbox"
    }
  ],
  "paths": {
    "/v3/vendor-credits/{vendorCreditId}": {
      "put": {
        "tags": [
          "vendor-credits"
        ],
        "summary": "Replace a vendor credit",
        "description": "Update the number of line items in a vendor credit. You can also update other vendor credit details.\n\nYou can use the PUT operation to add, remove, or replace the number of line items in a vendor credit. A set of rules apply with the PUT operation.\n* When you add a new line item, a new line item `id` is generated in the vendor credit.\n* When you omit an existing line item `id`, the line item is removed from the vendor credit.",
        "operationId": "replaceVendorCredit",
        "parameters": [
          {
            "name": "sessionId",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "API session ID generated with `/v3/login`",
              "nullable": true,
              "example": "{{session_id}}"
            }
          },
          {
            "name": "devKey",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Developer key generated with your BILL developer account",
              "nullable": true,
              "example": "{{developer_key}}"
            }
          },
          {
            "name": "vendorCreditId",
            "in": "path",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string",
              "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`.",
              "example": "{{vendor_credit_id}}"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReplaceVendorCreditRequestDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Replace a vendor credit response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VendorCreditResponseDto"
                }
              }
            }
          },
          "4XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BdcError": {
        "required": [
          "category",
          "code",
          "severity",
          "timestamp"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "code": {
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "message": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Param"
            }
          },
          "detail": {
            "type": "string"
          },
          "help": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "string",
        "enum": [
          "REQUEST",
          "APPLICATION",
          "SERVER",
          "DOWNSTREAM"
        ]
      },
      "CreditStatusDto": {
        "type": "string",
        "description": "Credit Status DTO.",
        "enum": [
          "FULLY_APPLIED",
          "NOT_APPLIED",
          "PARTIALLY_APPLIED",
          "IN_PROCESS",
          "UNDEFINED"
        ]
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "ReplaceVendorCreditLineItemDto": {
        "required": [
          "amount"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the vendor credit line item. The value begins with `vci`."
          },
          "description": {
            "type": "string",
            "description": "Vendor credit line item description"
          },
          "amount": {
            "type": "number",
            "description": "Vendor credit line item amount. For a vendor credit in an international currency (not USD), this value is in the local currency."
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VendorCreditLineItemClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the vendor credit line item"
              }
            ]
          }
        },
        "description": "Vendor Credit Replace Request Line Item."
      },
      "ReplaceVendorCreditRequestDto": {
        "required": [
          "creditDate",
          "referenceNumber",
          "vendorCreditLineItems",
          "vendorId"
        ],
        "type": "object",
        "properties": {
          "vendorId": {
            "minLength": 1,
            "type": "string",
            "description": "BILL-generated ID of the vendor. The value begins with `009`."
          },
          "referenceNumber": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "User-generated vendor credit number. This value can be in your chosen number scheme."
          },
          "creditDate": {
            "type": "string",
            "description": "Vendor credit issued date. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "description": {
            "type": "string",
            "description": "Vendor credit description"
          },
          "applyToChartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts used when the vendor credit is applied to a bill payment. The value begins with `0ca`."
          },
          "applyToBankAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the bank account used when the vendor credit is applied to a bill payment. The value begins with `bac`.\n\n**Note**: You can set only one of `applyToChartOfAccountId` or `applyToBankAccountId`."
          },
          "vendorCreditLineItems": {
            "minItems": 1,
            "type": "array",
            "description": "Vendor credit line item information",
            "items": {
              "$ref": "#/components/schemas/ReplaceVendorCreditLineItemDto"
            }
          }
        },
        "description": "Replace a vendor credit",
        "example": {
          "vendorId": "{{vendor_id}}",
          "referenceNumber": "202602-vendorcredit",
          "creditDate": "2026-12-28",
          "description": "Happy Vendor Credit (line item added)",
          "vendorCreditLineItems": [
            {
              "description": "Premium drummer gloves",
              "amount": 29.99
            },
            {
              "id": "{{vendor_credit_line_item_id01}}",
              "description": "Classic extreme drum sticks",
              "amount": 19.99
            },
            {
              "id": "{{vendor_credit_line_item_id02}}",
              "description": "Metal guitar picks (5-pack)",
              "amount": 50
            }
          ]
        }
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      },
      "VendorCreditLineItemClassificationsDto": {
        "type": "object",
        "properties": {
          "chartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts. The value begins with `0ca`."
          },
          "accountingClassId": {
            "type": "string",
            "description": "BILL-generated ID of the accounting class. The value begins with `cls`."
          },
          "departmentId": {
            "type": "string",
            "description": "BILL-generated ID of the department. The value begins with `0de`."
          },
          "jobId": {
            "type": "string",
            "description": "BILL-generated ID of the job. The value begins with `job`."
          },
          "locationId": {
            "type": "string",
            "description": "BILL-generated ID of the location. The value begins with `loc`."
          },
          "itemId": {
            "type": "string",
            "description": "BILL-generated ID of the item. The value begins with `0ii`."
          },
          "employeeId": {
            "type": "string",
            "description": "BILL-generated ID of the employee. The value begins with `emp`."
          },
          "customerId": {
            "type": "string",
            "description": "BILL-generated ID of the customer. The value begins with `0cu`."
          }
        },
        "description": "DTO for Bill Line Item classifications."
      },
      "VendorCreditLineItemResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the vendor credit line item. The value begins with `vci`."
          },
          "description": {
            "type": "string",
            "description": "Vendor credit line item description"
          },
          "amount": {
            "type": "number",
            "description": "Vendor credit line item amount. For a vendor credit in an international currency (not USD), this value is in the local currency."
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VendorCreditLineItemClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the vendor credit line item"
              }
            ]
          }
        },
        "description": "Vendor Credit Create Request Line Item."
      },
      "VendorCreditResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`."
          },
          "vendorId": {
            "type": "string",
            "description": "BILL-generated ID of the vendor. The value begins with `009`."
          },
          "referenceNumber": {
            "type": "string",
            "description": "User-generated vendor credit number. This value can be in your chosen number scheme."
          },
          "creditDate": {
            "type": "string",
            "description": "Vendor credit issued date. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "description": {
            "type": "string",
            "description": "Vendor credit description"
          },
          "archived": {
            "type": "boolean",
            "description": "Set as `true` if the vendor credit is archived"
          },
          "applyToChartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts used when the vendor credit is applied to a bill payment. The value begins with `0ca`."
          },
          "applyToBankAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the bank account used when the vendor credit is applied to a bill payment. The value begins with `bac`.\n\n**Note**: You can set only one of `applyToChartOfAccountId` or `applyToBankAccountId`."
          },
          "amount": {
            "type": "number",
            "description": "Vendor credit amount"
          },
          "appliedAmount": {
            "type": "number",
            "description": "Vendor credit amount applied to invoices"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CreditStatusDto"
              },
              {
                "description": "Vendor credit status."
              }
            ]
          },
          "createdTime": {
            "type": "string",
            "description": "Vendor credit created time",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "description": "Vendor credit updated time",
            "format": "date-time"
          },
          "vendorCreditLineItems": {
            "type": "array",
            "description": "Vendor credit line item information",
            "items": {
              "$ref": "#/components/schemas/VendorCreditLineItemResponseDto"
            }
          }
        },
        "description": "VendorCredit response Dto."
      }
    }
  }
}
```