{
  "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": [],
          "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
}
A Vendor Refund represents a transaction where a vendor returns value to a business. They are the counterpart to Customer Refunds. 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

​
id
string
required
Unique identifier for the vendor refund.
​
external_id
string
Unique ID of the vendor refund in your system for linking purposes. Idempotency key.
​
refunded_amount
integer
required
Amount refunded to the business in cents.
​
status
string
required
Status of the vendor refund.
​
completed_at
ISO8601 timestamp
required
Time when the vendor refund was completed.
​
allocations
array of VendorRefundAllocation objects
Allocations associated with this vendor refund. See Vendor Refund Allocation Object for details.
​
payments
array of VendorRefundPayment objects
Payments associated with this vendor refund. See Vendor Refund Payment Object for details.
​
transaction_tags
Array of Tags
Tags associated with the vendor refund.
​
memo
string
Memo for any text you would like to associate with the vendor refund.
​
metadata
json object
Arbitrary metadata you can include with the vendor refund.

​
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.
​
id
string
required
Unique identifier for the vendor refund allocation.
​
bill_id
string
ID of the bill this allocation is associated with.
​
amount
integer
required
Amount of the allocation in cents.
​
line_items
array of VendorRefundAllocationLineItem objects
Line items that make up this allocation. See Vendor Refund Allocation Line Item Object for details.
​
bill_external_id
string
External ID of the bill this allocation is associated with.
​
bill_line_item_id
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.
​
bill_line_item_external_id
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.
​
bill_payment_id
string
ID of the bill payment this allocation is associated with.
​
bill_payment_external_id
string
External ID of the bill payment this allocation is associated with.
​
vendor
Vendor object
The Vendor associated with this vendor refund allocation.
​
transaction_tags
Array of Tags
Tags associated with the vendor refund allocation.
​
memo
string
Memo for any text you would like to associate with the vendor refund allocation.
​
metadata
json object
Arbitrary metadata you can include with the vendor refund allocation.

​
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.
​
external_id
string
External identifier for the line item.
​
amount
integer
required
Amount of the line item in cents.
​
ledger_account
ChartAccount object
The ledger account associated with this line item.
​
prepayment_account
ChartAccount object
The prepayment account associated with this line item, if applicable.
​
transaction_tags
Array of Tags
Tags associated with the line item.
​
memo
string
Memo for any text you would like to associate with the line item.
​
metadata
json object
Arbitrary metadata you can include with the line item.

​
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_amounts 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.
​
id
string
required
Unique identifier for the payment.
​
external_id
string
Unique ID of the payment in your system for linking purposes. Idempotency key.
​
refunded_amount
integer
required
Amount refunded to the business in cents.
​
refund_processing_fee
integer
Fee paid by the business to receive the refund payment (typically a payment processing fee).
​
completed_at
ISO8601 timestamp
required
Time when the payment was completed.
​
method
string
required
Method of the payment (e.g., CREDIT_CARD, ACH, etc.).
​
processor
string
Processor used for the payment (e.g., STRIPE, SHOPIFY, etc.).
​
transaction_tags
Array of Tags
Tags associated with the vendor refund payment.
​
memo
string
Memo for any text you would like to associate with the vendor refund payment.
​
metadata
json object
Arbitrary metadata you can include with the vendor refund payment.

​
Simple Vendor Refund Creation Parameters

Use these parameters to create a simple vendor refund that fully refunds a single target and is fully paid.
​
external_id
string
Unique ID of the vendor refund in your system for linking purposes. Idempotency key.
​
completed_at
ISO8601 timestamp
required
When the vendor refund was completed and paid.
​
bill_id
string
The ID of the bill to refund. Cannot be used with other target identifiers.
​
bill_external_id
string
The external ID of the bill to refund. Cannot be used with other target identifiers.
​
bill_line_item_id
string
The ID of the bill line item to refund. Cannot be used with other target identifiers.
​
bill_line_item_external_id
string
The external ID of the bill line item to refund. Cannot be used with other target identifiers.
​
bill_payment_id
string
The ID of the bill payment to refund. Cannot be used with other target identifiers.
​
bill_payment_external_id
string
The external ID of the bill payment to refund. Cannot be used with other target identifiers.
​
refund_processing_fee
integer
Fee charged to the business for processing the refund in cents. Defaults to 0.
​
method
PaymentMethod enum
required
Method of the payment (e.g., CREDIT_CARD, ACH, etc.).
​
processor
string
Processor used for the payment (e.g., STRIPE, SHOPIFY, etc.).
​
tags
array of TagKeyValue objects
List of tags associated with this vendor refund.
​
memo
string
Memo for any text you would like to associate with the vendor refund.
​
metadata
json object
Arbitrary metadata you can include with the vendor refund.

​
Itemized Vendor Refund Creation Parameters

Use these parameters to create an itemized vendor refund with full control over allocations and payments.
​
external_id
string
Unique ID of the vendor refund in your system for linking purposes. Idempotency key.
​
refunded_amount
integer
required
The total amount of the vendor refund in cents. Must equal the sum of all allocation amounts.
​
completed_at
ISO8601 timestamp
required
When the vendor refund was completed.
​
allocations
array of VendorRefundAllocationParams objects
required
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.
​
payments
array of VendorRefundPaymentParams objects
required
The payment methods and amounts used to receive the vendor refund.
​
tags
array of TagKeyValue objects
List of tags associated with this vendor refund.
​
memo
string
Memo for any text you would like to associate with the vendor refund.
​
metadata
json object
Arbitrary metadata you can include with the vendor refund.
{
  "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": [],
          "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
}