{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_id": "31415926535",
  "refunded_amount": 123,
  "status": "PAID",
  "completed_at": "2023-11-07T05:31:56Z",
  "is_dedicated": false,
  "allocations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": 123,
      "line_items": [
        {
          "external_id": "line-item-1",
          "amount": 123,
          "ledger_account": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "name": "Revenue",
            "account_number": "4000"
          },
          "prepayment_account": null,
          "transaction_tags": [],
          "memo": null,
          "metadata": null
        }
      ],
      "invoice_external_id": "invoice-123",
      "invoice_line_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_line_item_external_id": "line-item-123",
      "invoice_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_payment_external_id": "payment-123",
      "customer": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "external_id": "31415926535",
        "individual_name": "John Doe",
        "company_name": "Acme Corp",
        "email": "john@example.com",
        "mobile_phone": "555-123-4567",
        "office_phone": "555-987-6543",
        "address_string": "123 Main St, Anytown, CA 90210",
        "notes": "VIP customer",
        "status": "ACTIVE",
        "transaction_tags": [
          {
            "key": "CustomerType",
            "value": "Premium",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": null
          }
        ]
      },
      "transaction_tags": [
        {
          "key": "RefundReason",
          "value": "CustomerRequest",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "deleted_at": null
        }
      ],
      "memo": null,
      "metadata": null
    }
  ],
  "payments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "31415926535",
      "refunded_amount": 123,
      "refund_processing_fee": 15,
      "completed_at": "2023-11-07T05:31:56Z",
      "method": "CREDIT_CARD",
      "processor": "STRIPE",
      "refunded_payment_fees": [
        {
          "account": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "description": "Processing fee refund",
          "fee_amount": 10
        }
      ],
      "transaction_tags": [
        {
          "key": "ProcessorReference",
          "value": "ref_12345",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "deleted_at": null
        }
      ],
      "memo": null,
      "metadata": null
    }
  ],
  "payouts": [],
  "transaction_tags": [
    {
      "key": "Department",
      "value": "CustomerService",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": null
    }
  ],
  "memo": null,
  "metadata": null
}
A Refund represents a transaction that returns value from a business to a customer. Each refund has one or more Refund Allocations (targets) and zero or more Refund Payments.

​
Creating Refunds

There are two ways to create refunds:

​
Simple Refunds

Use simple refunds when you want to fully refund a single target (invoice, invoice line item, or invoice 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 Refunds

Use itemized 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 disbursed)
  • Custom allocation amounts or payment structures
With itemized refunds, you specify all allocations and payments explicitly.

​
Refund Object

​
Attributes

​
id
string
required
Unique identifier for the refund.
​
external_id
string
Unique ID of the refund in your system for linking purposes. Idempotency key.
​
refunded_amount
integer
required
Amount refunded to the customer in cents.
​
status
string
required
Status of the refund.
​
completed_at
ISO8601 timestamp
required
Time when the refund was completed.
​
is_dedicated
boolean
required
Whether this refund is dedicated or not. Dedicated refunds can only have one allocation and one payment, and their allocation target cannot be changed.
​
allocations
array of RefundAllocation objects
Allocations associated with this refund. See Refund Allocation Object for details.
​
payments
array of RefundPayment objects
Payments associated with this refund. See Refund Payment Object for details.
​
payouts
array of Payout objects
Payouts associated with this refund.
​
transaction_tags
Array of Tags
Tags associated with the refund.
​
memo
string
Memo for any text you would like to associate with the refund.
​
metadata
json object
Arbitrary metadata you can include with the refund.
​
reference_number
string
Any (typically user-visible) identifier you would like to associate with the refund. Can be used to filter when listing refunds.

​
Refund Allocation Object

A Refund Allocation represents one of the targets of a refund. It can reference a specific invoice, invoice line item, invoice payment, or customer. For example, a refund can apply to two separate invoices if the invoices have the same customer. The total of the amounts of the refund allocations must add up to the refund amount.
​
id
string
required
Unique identifier for the refund allocation.
​
invoice_id
string
ID of the invoice this allocation is associated with.
​
amount
integer
required
Amount of the allocation in cents.
​
line_items
array of RefundAllocationLineItem objects
Line items that make up this allocation. See Refund Allocation Line Item Object for details.
​
invoice_external_id
string
External ID of the invoice this allocation is associated with.
​
invoice_line_item_id
string
ID of the invoice line item this allocation is associated with. If specified, must not refer to a different invoice than invoice_id or invoice_external_id.
​
invoice_line_item_external_id
string
The external ID of the invoice line item to refund. If specified alongside invoice_line_item_id, they must refer to the same invoice line item.
​
invoice_payment_id
string
ID of the invoice payment this allocation is associated with.
​
invoice_payment_external_id
string
External ID of the invoice payment this allocation is associated with.
​
customer
Customer object
The Customer associated with this refund allocation.
​
transaction_tags
Array of Tags
Tags associated with the refund allocation.
​
memo
string
Memo for any text you would like to associate with the refund allocation.
​
metadata
json object
Arbitrary metadata you can include with the refund allocation.
​
reference_number
string
Any (typically user-visible) identifier you would like to associate with the refund allocation.

​
Refund Allocation Line Item Object

A Refund Allocation Line Item represents a specific line within a 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 ledger 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.
​
reference_number
string
Any (typically user-visible) identifier you would like to associate with the refund pyment. Can be used to filter when listing refund payments.

​
Refund Payment Object

A Refund Payment represents a money movement by which the refund was disbursed to the customer. A refund with zero payments represents a refund that is owed to a customer but has not yet been sent. A refund can have many payments so long as the total of their refunded_amounts does not exceed the total amount of the refund. Refund payments are matchable to bank transactions and are therefore the means by which 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 customer in cents.
​
refund_processing_fee
integer
Fee paid by the business to make 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.).
​
refunded_payment_fees
array of RefundedPaymentFee objects
Refunded payment fees associated with the refund payment. See Refunded Payment Fee Object for details.
​
transaction_tags
Array of Tags
Tags associated with the refund payment.
​
memo
string
Memo for any text you would like to associate with the refund payment.
​
metadata
json object
Arbitrary metadata you can include with the refund payment.

​
Refunded Payment Fee Object

A Refunded Payment Fee represents a fee that was refunded as part of a refund payment. This differs from the ‘refund_processing_fee’ field on the refund payment, since that is paid by the business (typically to a payment processor), whereas this is refunded from the payment processor back to the business.
​
account
AccountIdentifier object
required
Identifier of the ledger account for the refunded payment fee.
​
description
string
Description of the fee that the refunded payment fee refunds.
​
fee_amount
integer
required
Amount of the fee refund in cents.

​
Simple Refund Creation Parameters

Use these parameters to create a simple refund that fully refunds a single target (invoice, invoice line item, or invoice payment) and is fully paid.
​
external_id
string
Unique ID of the refund in your system for linking purposes. Idempotency key.
​
completed_at
ISO8601 timestamp
required
When the refund was completed and paid.
​
invoice_id
string
The ID of the invoice to refund. Cannot be used with other target identifiers.
​
invoice_external_id
string
The external ID of the invoice to refund. Cannot be used with other target identifiers.
​
invoice_line_item_id
string
The ID of the invoice line item to refund. Cannot be used with other target identifiers.
​
invoice_line_item_external_id
string
The external ID of the invoice line item to refund. Cannot be used with other target identifiers.
​
invoice_payment_id
string
The ID of the invoice payment to refund. Cannot be used with other target identifiers.
​
invoice_payment_external_id
string
The external ID of the invoice 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 refund.
​
memo
string
Memo for any text you would like to associate with the refund.
​
metadata
json object
Arbitrary metadata you can include with the refund.

​
Itemized Refund Creation Parameters

Use these parameters to create an itemized refund with full control over allocations and payments.
​
external_id
string
Unique ID of the refund in your system for linking purposes. Idempotency key.
​
refunded_amount
integer
required
The total amount of the refund in cents. Must equal the sum of all allocation amounts.
​
completed_at
ISO8601 timestamp
required
When the refund was completed.
​
allocations
array of RefundAllocationParams objects
required
The targets of the refund. Each allocation specifies how much of the refund should be applied to a specific invoice, line item, payment, or customer.
​
payments
array of RefundPaymentParams objects
required
The payment methods and amounts used to process the refund.
​
tags
array of TagKeyValue objects
List of tags associated with this refund.
​
memo
string
Memo for any text you would like to associate with the refund.
​
metadata
json object
Arbitrary metadata you can include with the refund.
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_id": "31415926535",
  "refunded_amount": 123,
  "status": "PAID",
  "completed_at": "2023-11-07T05:31:56Z",
  "is_dedicated": false,
  "allocations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": 123,
      "line_items": [
        {
          "external_id": "line-item-1",
          "amount": 123,
          "ledger_account": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "name": "Revenue",
            "account_number": "4000"
          },
          "prepayment_account": null,
          "transaction_tags": [],
          "memo": null,
          "metadata": null
        }
      ],
      "invoice_external_id": "invoice-123",
      "invoice_line_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_line_item_external_id": "line-item-123",
      "invoice_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_payment_external_id": "payment-123",
      "customer": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "external_id": "31415926535",
        "individual_name": "John Doe",
        "company_name": "Acme Corp",
        "email": "john@example.com",
        "mobile_phone": "555-123-4567",
        "office_phone": "555-987-6543",
        "address_string": "123 Main St, Anytown, CA 90210",
        "notes": "VIP customer",
        "status": "ACTIVE",
        "transaction_tags": [
          {
            "key": "CustomerType",
            "value": "Premium",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": null
          }
        ]
      },
      "transaction_tags": [
        {
          "key": "RefundReason",
          "value": "CustomerRequest",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "deleted_at": null
        }
      ],
      "memo": null,
      "metadata": null
    }
  ],
  "payments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "31415926535",
      "refunded_amount": 123,
      "refund_processing_fee": 15,
      "completed_at": "2023-11-07T05:31:56Z",
      "method": "CREDIT_CARD",
      "processor": "STRIPE",
      "refunded_payment_fees": [
        {
          "account": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "description": "Processing fee refund",
          "fee_amount": 10
        }
      ],
      "transaction_tags": [
        {
          "key": "ProcessorReference",
          "value": "ref_12345",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "deleted_at": null
        }
      ],
      "memo": null,
      "metadata": null
    }
  ],
  "payouts": [],
  "transaction_tags": [
    {
      "key": "Department",
      "value": "CustomerService",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": null
    }
  ],
  "memo": null,
  "metadata": null
}