> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vendor Refund object

A Vendor Refund represents a transaction where a vendor returns value to a business. They are the counterpart to [Customer Refunds](/api-reference/refunds/refund). Each vendor refund has one or more Vendor Refund Allocations (targets) and zero or more Vendor Refund Payments.

## Creating Vendor Refunds

There are two ways to create vendor refunds:

### Simple Vendor Refunds

Use simple vendor refunds when you want to fully refund a single target (bill, bill line item, or bill payment) and the refund is fully paid. Layer automatically:

* Calculates the refund amount based on what can be refunded from the target
* Creates one allocation that perfectly cancels out the target
* Creates one refund payment that pays the refund in full

### Itemized Vendor Refunds

Use itemized vendor refunds for more complex scenarios including:

* Refunding multiple targets in a single refund
* Partial refunds that don't fully cancel out the target
* Unpaid refunds (refunds owed but not yet received)
* Custom allocation amounts or payment structures

With itemized vendor refunds, you specify all allocations and payments explicitly.

## Vendor Refund Object

### Attributes

<ParamField body="id" type="string" required="true">
  Unique identifier for the vendor refund.
</ParamField>

<ParamField body="external_id" type="string">
  Unique ID of the vendor refund in your system for linking purposes. **Idempotency key**.
</ParamField>

<ParamField body="refunded_amount" type="integer" required="true">
  Amount refunded to the business in cents.
</ParamField>

<ParamField body="status" type="string" required="true">
  Status of the vendor refund.
</ParamField>

<ParamField body="completed_at" type="ISO8601 timestamp" required="true">
  Time when the vendor refund was completed.
</ParamField>

<ParamField body="allocations" type="array of VendorRefundAllocation objects">
  Allocations associated with this vendor refund. See [Vendor Refund Allocation Object](#vendor-refund-allocation-object) for details.
</ParamField>

<ParamField body="payments" type="array of VendorRefundPayment objects">
  Payments associated with this vendor refund. See [Vendor Refund Payment Object](#vendor-refund-payment-object) for details.
</ParamField>

<ParamField body="transaction_tags" type="Array of Tags">
  Tags associated with the vendor refund.

  <Expandable title="Tag properties">
    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the vendor refund.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the vendor refund.
</ParamField>

## Vendor Refund Allocation Object

A Vendor Refund Allocation represents one of the targets of a vendor refund. It can reference a specific bill, bill line item, bill payment, or vendor.
For example, a vendor refund can apply to two separate bills if the bills are from the same vendor.
The total of the amounts of the vendor refund allocations must add up to the refund amount.

<ParamField body="id" type="string" required="true">
  Unique identifier for the vendor refund allocation.
</ParamField>

<ParamField body="bill_id" type="string">
  ID of the bill this allocation is associated with.
</ParamField>

<ParamField body="amount" type="integer" required="true">
  Amount of the allocation in cents.
</ParamField>

<ParamField body="line_items" type="array of VendorRefundAllocationLineItem objects">
  Line items that make up this allocation. See [Vendor Refund Allocation Line Item Object](#vendor-refund-allocation-line-item-object) for details.
</ParamField>

<ParamField body="bill_external_id" type="string">
  External ID of the bill this allocation is associated with.
</ParamField>

<ParamField body="bill_line_item_id" type="string">
  ID of the bill line item this allocation is associated with. If specified, must not refer to a different bill than `bill_id` or `bill_external_id`.
</ParamField>

<ParamField body="bill_line_item_external_id" type="string">
  The external ID of the bill line item to refund. If specified alongside `bill_line_item_id`, they must refer to the same bill line item.
</ParamField>

<ParamField body="bill_payment_id" type="string">
  ID of the bill payment this allocation is associated with.
</ParamField>

<ParamField body="bill_payment_external_id" type="string">
  External ID of the bill payment this allocation is associated with.
</ParamField>

<ParamField body="vendor" type="Vendor object">
  The [Vendor](/api-reference/vendor/vendor) associated with this vendor refund allocation.
</ParamField>

<ParamField body="transaction_tags" type="Array of Tags">
  Tags associated with the vendor refund allocation.

  <Expandable title="Tag properties">
    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the vendor refund allocation.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the vendor refund allocation.
</ParamField>

## Vendor Refund Allocation Line Item Object

A Vendor Refund Allocation Line Item represents a specific line within a vendor refund allocation, allowing for detailed breakdowns of how the allocation amount is distributed across different ledger accounts.

<ParamField body="external_id" type="string">
  External identifier for the line item.
</ParamField>

<ParamField body="amount" type="integer" required="true">
  Amount of the line item in cents.
</ParamField>

<ParamField body="ledger_account" type="ChartAccount object">
  The ledger account associated with this line item.
</ParamField>

<ParamField body="prepayment_account" type="ChartAccount object">
  The prepayment account associated with this line item, if applicable.
</ParamField>

<ParamField body="transaction_tags" type="Array of Tags">
  Tags associated with the line item.

  <Expandable title="Tag properties">
    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the line item.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the line item.
</ParamField>

## Vendor Refund Payment Object

A Vendor Refund Payment represents a money movement by which the vendor refund was received by the business.
A vendor refund with zero payments represents a refund that is owed to the business but has not yet been received.

A vendor refund can have many payments so long as the total of their `refunded_amount`s does not exceed the total amount of the refund.

Vendor refund payments are matchable to bank transactions and are therefore the means by which vendor refunds are reconciled with bank accounts.

<ParamField body="id" type="string" required="true">
  Unique identifier for the payment.
</ParamField>

<ParamField body="external_id" type="string">
  Unique ID of the payment in your system for linking purposes. **Idempotency key**.
</ParamField>

<ParamField body="refunded_amount" type="integer" required="true">
  Amount refunded to the business in cents.
</ParamField>

<ParamField body="refund_processing_fee" type="integer">
  Fee paid by the business to receive the refund payment (typically a payment processing fee).
</ParamField>

<ParamField body="completed_at" type="ISO8601 timestamp" required="true">
  Time when the payment was completed.
</ParamField>

<ParamField body="method" type="string" required="true">
  Method of the payment (e.g., `CREDIT_CARD`, `ACH`, etc.).
</ParamField>

<ParamField body="processor" type="string">
  Processor used for the payment (e.g., `STRIPE`, `SHOPIFY`, etc.).
</ParamField>

<ParamField body="transaction_tags" type="Array of Tags">
  Tags associated with the vendor refund payment.

  <Expandable title="Tag properties">
    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the vendor refund payment.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the vendor refund payment.
</ParamField>

## Simple Vendor Refund Creation Parameters

Use these parameters to create a simple vendor refund that fully refunds a single target and is fully paid.

<ParamField body="external_id" type="string">
  Unique ID of the vendor refund in your system for linking purposes. **Idempotency key**.
</ParamField>

<ParamField body="completed_at" type="ISO8601 timestamp" required="true">
  When the vendor refund was completed and paid.
</ParamField>

<ParamField body="bill_id" type="string">
  The ID of the bill to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="bill_external_id" type="string">
  The external ID of the bill to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="bill_line_item_id" type="string">
  The ID of the bill line item to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="bill_line_item_external_id" type="string">
  The external ID of the bill line item to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="bill_payment_id" type="string">
  The ID of the bill payment to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="bill_payment_external_id" type="string">
  The external ID of the bill payment to refund. Cannot be used with other target identifiers.
</ParamField>

<ParamField body="refund_processing_fee" type="integer">
  Fee charged to the business for processing the refund in cents. Defaults to 0.
</ParamField>

<ParamField body="method" type="PaymentMethod enum" required="true">
  Method of the payment (e.g., `CREDIT_CARD`, `ACH`, etc.).
</ParamField>

<ParamField body="processor" type="string">
  Processor used for the payment (e.g., `STRIPE`, `SHOPIFY`, etc.).
</ParamField>

<ParamField body="tags" type="array of TagKeyValue objects">
  Tags to apply to the vendor refund. Tags are key-value pairs that can be used to categorize and filter vendor refunds.

  <Expandable title="TagKeyValue properties">
    <ParamField body="key" required="true" type="string">
      The tag dimension key (e.g., "department", "project", "location")
    </ParamField>

    <ParamField body="dimension_display_name" type="string">
      Optional display name for the tag dimension. If the dimension doesn't exist, this will be used as its display name.
    </ParamField>

    <ParamField body="value" required="true" type="string">
      The tag value (e.g., "engineering", "project-alpha", "san-francisco")
    </ParamField>

    <ParamField body="value_display_name" type="string">
      Optional display name for the tag value. If the value doesn't exist, this will be used as its display name.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the vendor refund.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the vendor refund.
</ParamField>

## Itemized Vendor Refund Creation Parameters

Use these parameters to create an itemized vendor refund with full control over allocations and payments.

<ParamField body="external_id" type="string">
  Unique ID of the vendor refund in your system for linking purposes. **Idempotency key**.
</ParamField>

<ParamField body="refunded_amount" type="integer" required="true">
  The total amount of the vendor refund in cents. Must equal the sum of all allocation amounts.
</ParamField>

<ParamField body="completed_at" type="ISO8601 timestamp" required="true">
  When the vendor refund was completed.
</ParamField>

<ParamField body="allocations" type="array of VendorRefundAllocationParams objects" required="true">
  The targets of the vendor refund. Each allocation specifies how much of the refund should be applied to a specific bill, line item, payment, or vendor.

  <Expandable title="VendorRefundAllocationParams properties">
    <ResponseField name="external_id" type="string">
      External identifier for the allocation.
    </ResponseField>

    <ResponseField name="total_amount" required="true" type="integer">
      Total amount of this allocation in cents. Must equal the sum of all line item amounts.
    </ResponseField>

    <ResponseField name="line_items" required="true" type="array of LineItemParams objects">
      Line items that make up this allocation.
    </ResponseField>

    <ResponseField name="bill_id" type="string">
      ID of the bill this allocation targets.
    </ResponseField>

    <ResponseField name="bill_external_id" type="string">
      External ID of the bill this allocation targets.
    </ResponseField>

    <ResponseField name="bill_line_item_id" type="string">
      ID of the bill line item this allocation targets.
    </ResponseField>

    <ResponseField name="bill_line_item_external_id" type="string">
      External ID of the bill line item this allocation targets.
    </ResponseField>

    <ResponseField name="bill_payment_id" type="string">
      ID of the bill payment this allocation targets.
    </ResponseField>

    <ResponseField name="bill_payment_external_id" type="string">
      External ID of the bill payment this allocation targets.
    </ResponseField>

    <ResponseField name="vendor_id" type="string">
      ID of the vendor this allocation targets.
    </ResponseField>

    <ResponseField name="vendor_external_id" type="string">
      External ID of the vendor this allocation targets.
    </ResponseField>

    <ResponseField name="tags" type="array of TagKeyValue objects">
      Tags for this allocation.
    </ResponseField>

    <ResponseField name="memo" type="string">
      Memo for this allocation.
    </ResponseField>

    <ResponseField name="metadata" type="json object">
      Metadata for this allocation.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="payments" type="array of VendorRefundPaymentParams objects" required="true">
  The payment methods and amounts used to receive the vendor refund.

  <Expandable title="VendorRefundPaymentParams properties">
    <ResponseField name="external_id" type="string">
      External identifier for the payment.
    </ResponseField>

    <ResponseField name="refunded_amount" required="true" type="integer">
      Amount refunded to the business in cents.
    </ResponseField>

    <ResponseField name="refund_processing_fee" type="integer">
      Fee charged to the business for processing this payment.
    </ResponseField>

    <ResponseField name="completed_at" required="true" type="ISO8601 timestamp">
      When this payment was completed.
    </ResponseField>

    <ResponseField name="method" required="true" type="PaymentMethod enum">
      Payment method used.
    </ResponseField>

    <ResponseField name="processor" type="string">
      Processor used for this payment.
    </ResponseField>

    <ResponseField name="tags" type="array of TagKeyValue objects">
      Tags for this payment.
    </ResponseField>

    <ResponseField name="memo" type="string">
      Memo for this payment.
    </ResponseField>

    <ResponseField name="metadata" type="json object">
      Metadata for this payment.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="tags" type="array of TagKeyValue objects">
  List of tags associated with this vendor refund.
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the vendor refund.
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the vendor refund.
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_id": "vendor-refund-123",
    "refunded_amount": 500,
    "status": "PAID",
    "completed_at": "2023-11-07T05:31:56Z",
    "allocations": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "bill_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "amount": 500,
        "line_items": [
          {
            "external_id": "line-item-1",
            "amount": 500,
            "ledger_account": {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "name": "Office Supplies",
              "account_number": "6200"
            },
            "prepayment_account": null,
            "transaction_tags": [
              {
                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "key": "department",
                "value": "sales",
                "dimension_display_name": "Department",
                "value_display_name": "Sales Team",
                "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
                "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                "created_at": "2024-02-27T02:16:40.389772Z",
                "updated_at": "2024-02-27T02:16:40.389772Z",
                "deleted_at": null,
                "archived_at": null
              }
            ],
            "memo": null,
            "metadata": null
          }
        ],
        "bill_external_id": "bill-456",
        "bill_line_item_id": null,
        "bill_line_item_external_id": null,
        "bill_payment_id": null,
        "bill_payment_external_id": null,
        "vendor": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "external_id": "vendor-789",
          "individual_name": null,
          "company_name": "Office Supply Co",
          "email": "accounts@officesupply.com",
          "mobile_phone": null,
          "office_phone": "555-123-4567",
          "address_string": "456 Supply St, Business City, NY 10001",
          "notes": "Regular office supply vendor",
          "status": "ACTIVE",
          "transaction_tags": []
        },
        "transaction_tags": [
          {
            "key": "RefundReason",
            "value": "DefectiveItems",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": null
          }
        ],
        "memo": "Refund for defective office supplies",
        "metadata": null
      }
    ],
    "payments": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "external_id": "payment-321",
        "refunded_amount": 500,
        "refund_processing_fee": 5,
        "completed_at": "2023-11-07T05:31:56Z",
        "method": "ACH",
        "processor": "STRIPE",
        "transaction_tags": [
          {
            "key": "ProcessorReference",
            "value": "ach_1234567890",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": null
          }
        ],
        "memo": null,
        "metadata": null
      }
    ],
    "transaction_tags": [
      {
        "key": "Department",
        "value": "Procurement",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "deleted_at": null
      }
    ],
    "memo": "Monthly office supply refund",
    "metadata": null
  }
  ```
</ResponseExample>