Vendor Refund object

{
  "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
}

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

string

required

Unique identifier for the vendor refund.

string

Unique ID of the vendor refund in your system for linking purposes. Idempotency key.

integer

required

Amount refunded to the business in cents.

string

required

Status of the vendor refund.

ISO8601 timestamp

required

Time when the vendor refund was completed.

array of VendorRefundAllocation objects

Allocations associated with this vendor refund. See Vendor Refund Allocation Object for details.

array of VendorRefundPayment objects

Payments associated with this vendor refund. See Vendor Refund Payment Object for details.

Array of Tags

Tags associated with the vendor refund.

Show Tag properties

string

required

The tag’s key

string

required

The tag’s value

ISO8601 timestamp

required

When the tag was created

ISO8601 timestamp

required

When the tag was last updated

ISO8601 timestamp

When the tag was deleted

string

Memo for any text you would like to associate with the vendor refund.

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.

string

required

Unique identifier for the vendor refund allocation.

string

ID of the bill this allocation is associated with.

integer

required

Amount of the allocation in cents.

array of VendorRefundAllocationLineItem objects

Line items that make up this allocation. See Vendor Refund Allocation Line Item Object for details.

string

External ID of the bill this allocation is associated with.

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.

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.

string

ID of the bill payment this allocation is associated with.

string

External ID of the bill payment this allocation is associated with.

Vendor object

The Vendor associated with this vendor refund allocation.

Array of Tags

Tags associated with the vendor refund allocation.

Show Tag properties

string

required

The tag’s key

string

required

The tag’s value

ISO8601 timestamp

required

When the tag was created

ISO8601 timestamp

required

When the tag was last updated

ISO8601 timestamp

When the tag was deleted

string

Memo for any text you would like to associate with the vendor refund allocation.

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.

string

External identifier for the line item.

integer

required

Amount of the line item in cents.

ChartAccount object

The ledger account associated with this line item.

ChartAccount object

The prepayment account associated with this line item, if applicable.

Array of Tags

Tags associated with the line item.

Show Tag properties

string

required

The tag’s key

string

required

The tag’s value

ISO8601 timestamp

required

When the tag was created

ISO8601 timestamp

required

When the tag was last updated

ISO8601 timestamp

When the tag was deleted

string

Memo for any text you would like to associate with the line item.

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.

string

required

Unique identifier for the payment.

string

Unique ID of the payment in your system for linking purposes. Idempotency key.

integer

required

Amount refunded to the business in cents.

integer

Fee paid by the business to receive the refund payment (typically a payment processing fee).

ISO8601 timestamp

required

Time when the payment was completed.

string

required

Method of the payment (e.g., CREDIT_CARD, ACH, etc.).

string

Processor used for the payment (e.g., STRIPE, SHOPIFY, etc.).

Array of Tags

Tags associated with the vendor refund payment.

Show Tag properties

string

required

The tag’s key

string

required

The tag’s value

ISO8601 timestamp

required

When the tag was created

ISO8601 timestamp

required

When the tag was last updated

ISO8601 timestamp

When the tag was deleted

string

Memo for any text you would like to associate with the vendor refund payment.

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.

string

Unique ID of the vendor refund in your system for linking purposes. Idempotency key.

ISO8601 timestamp

required

When the vendor refund was completed and paid.

string

The ID of the bill to refund. Cannot be used with other target identifiers.

string

The external ID of the bill to refund. Cannot be used with other target identifiers.

string

The ID of the bill line item to refund. Cannot be used with other target identifiers.

string

The external ID of the bill line item to refund. Cannot be used with other target identifiers.

string

The ID of the bill payment to refund. Cannot be used with other target identifiers.

string

The external ID of the bill payment to refund. Cannot be used with other target identifiers.

integer

Fee charged to the business for processing the refund in cents. Defaults to 0.

PaymentMethod enum

required

Method of the payment (e.g., CREDIT_CARD, ACH, etc.).

string

Processor used for the payment (e.g., STRIPE, SHOPIFY, etc.).

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.

Show TagKeyValue properties

string

required

The tag dimension key (e.g., “department”, “project”, “location”)

string

Optional display name for the tag dimension. If the dimension doesn’t exist, this will be used as its display name.

string

required

The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)

string

Optional display name for the tag value. If the value doesn’t exist, this will be used as its display name.

string

Memo for any text you would like to associate with the vendor refund.

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.

string

Unique ID of the vendor refund in your system for linking purposes. Idempotency key.

integer

required

The total amount of the vendor refund in cents. Must equal the sum of all allocation amounts.

ISO8601 timestamp

required

When the vendor refund was completed.

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.

Show VendorRefundAllocationParams properties

string

External identifier for the allocation.

integer

required

Total amount of this allocation in cents. Must equal the sum of all line item amounts.

array of LineItemParams objects

required

Line items that make up this allocation.

string

ID of the bill this allocation targets.

string

External ID of the bill this allocation targets.

string

ID of the bill line item this allocation targets.

string

External ID of the bill line item this allocation targets.

string

ID of the bill payment this allocation targets.

string

External ID of the bill payment this allocation targets.

string

ID of the vendor this allocation targets.

string

External ID of the vendor this allocation targets.

array of TagKeyValue objects

Tags for this allocation.

string

Memo for this allocation.

json object

Metadata for this allocation.

array of VendorRefundPaymentParams objects

required

The payment methods and amounts used to receive the vendor refund.

Show VendorRefundPaymentParams properties

string

External identifier for the payment.

integer

required

Amount refunded to the business in cents.

integer

Fee charged to the business for processing this payment.

ISO8601 timestamp

required

When this payment was completed.

PaymentMethod enum

required

Payment method used.

string

Processor used for this payment.

array of TagKeyValue objects

Tags for this payment.

string

Memo for this payment.

json object

Metadata for this payment.

array of TagKeyValue objects

List of tags associated with this vendor refund.

string

Memo for any text you would like to associate with the vendor refund.

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": [
            {
              "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
}

Delete vendor credit List vendor refunds

⌘I

Businesses

Financial Activity

Accounting Reports

Platform Configuration

Activity Metrics

Quickbooks

Vendor Refund object

Creating Vendor Refunds

Simple Vendor Refunds

Itemized Vendor Refunds

Vendor Refund Object

Attributes

Vendor Refund Allocation Object

Vendor Refund Allocation Line Item Object

Vendor Refund Payment Object

Simple Vendor Refund Creation Parameters

Itemized Vendor Refund Creation Parameters

​Creating Vendor Refunds

​Simple Vendor Refunds

​Itemized Vendor Refunds

​Vendor Refund Object

​Attributes

​Vendor Refund Allocation Object

​Vendor Refund Allocation Line Item Object

​Vendor Refund Payment Object

​Simple Vendor Refund Creation Parameters

​Itemized Vendor Refund Creation Parameters

Creating Vendor Refunds

Simple Vendor Refunds

Itemized Vendor Refunds

Vendor Refund Object

Attributes

Vendor Refund Allocation Object

Vendor Refund Allocation Line Item Object

Vendor Refund Payment Object

Simple Vendor Refund Creation Parameters

Itemized Vendor Refund Creation Parameters