Refund object

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

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.

Show Tag properties

key

string

required

The tag’s key

value

string

required

The tag’s value

created_at

ISO8601 timestamp

required

When the tag was created

updated_at

ISO8601 timestamp

required

When the tag was last updated

deleted_at

ISO8601 timestamp

When the tag was deleted

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.

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.

Show Tag properties

key

string

required

The tag’s key

value

string

required

The tag’s value

created_at

ISO8601 timestamp

required

When the tag was created

updated_at

ISO8601 timestamp

required

When the tag was last updated

deleted_at

ISO8601 timestamp

When the tag was deleted

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.

Show Tag properties

key

string

required

The tag’s key

value

string

required

The tag’s value

created_at

ISO8601 timestamp

required

When the tag was created

updated_at

ISO8601 timestamp

required

When the tag was last updated

deleted_at

ISO8601 timestamp

When the tag was deleted

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.

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.

Show Tag properties

key

string

required

The tag’s key

value

string

required

The tag’s value

created_at

ISO8601 timestamp

required

When the tag was created

updated_at

ISO8601 timestamp

required

When the tag was last updated

deleted_at

ISO8601 timestamp

When the tag was deleted

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.

Show TagKeyValue properties

key

string

required

The tag’s key

value

string

required

The tag’s value

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.

Show RefundAllocationParams properties

external_id

string

External identifier for the allocation.

total_amount

integer

required

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

line_items

array of LineItemParams objects

required

Line items that make up this allocation.

invoice_id

string

ID of the invoice this allocation targets.

invoice_external_id

string

External ID of the invoice this allocation targets.

invoice_line_item_id

string

ID of the invoice line item this allocation targets.

invoice_line_item_external_id

string

External ID of the invoice line item this allocation targets.

invoice_payment_id

string

ID of the invoice payment this allocation targets.

invoice_payment_external_id

string

External ID of the invoice payment this allocation targets.

customer_id

string

ID of the customer this allocation targets.

customer_external_id

string

External ID of the customer this allocation targets.

tags

array of TagKeyValue objects

Tags for this allocation.

memo

string

Memo for this allocation.

metadata

json object

Metadata for this allocation.

payments

array of RefundPaymentParams objects

required

The payment methods and amounts used to process the refund.

Show RefundPaymentParams properties

external_id

string

External identifier for the payment.

refunded_amount

integer

required

Amount refunded to the customer in cents.

refund_processing_fee

integer

Fee charged to the business for processing this payment.

completed_at

ISO8601 timestamp

required

When this payment was completed.

method

PaymentMethod enum

required

Payment method used.

processor

string

Processor used for this payment.

refunded_payment_fees

array of RefundedPaymentFeeInput objects

Fees refunded as part of this payment.

tags

array of TagKeyValue objects

Tags for this payment.

memo

string

Memo for this payment.

metadata

json object

Metadata for this payment.

reference_number

string

Any (typically user-visible) identifier for this payment.

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
}

Dedicated Refunds

Dedicated refunds are a refunds that are created alongside invoices, invoice line items, and invoice payments. They provide a streamlined way to create refunds during the invoice creation or payment recording process. They are intended for when you know at the time of importing an invoice, invoice line item, or payment that it will be refunded, and want to create everything in one API call. Each dedicated refund has exactly one allocation and one payment. Once created, the allocation target cannot be changed Dedicated refunds can be included when creating: Invoices: Add dedicated_refunds array to the invoice body Invoice Line Items: Add dedicated_refunds array to any line item Invoice Payments: Add dedicated_refunds array to any payment within an invoice

Simple vs Itemized Dedicated Refunds

When creating dedicated refunds, Layer will automatically determine whether to create them as simple or itemized refunds based on the parameters you provide: Simple Dedicated Refunds (see Simple Refunds):

Created when you don’t specify the line_items parameter
Layer automatically calculates the refund amount and creates a single allocation
Ideal for straightforward refunds where you want to refund the full amount of a target

Itemized Dedicated Refunds (see Itemized Refunds):

Created when you provide the line_items parameter with detailed allocation breakdowns
You have full control over how the refund amount is distributed across different ledger accounts
Required for complex refunds involving multiple accounts or partial amounts

Create Dedicated Refund Parameters Object

external_id

string

External ID for the refund within your platform. Idempotency key.

account_identifier

AccountIdentifier object

The Account Identifier for the refund allocation. If not specified, will use the appropriate account based on the target.

line_items

array of CreateCustomerRefundAllocationLineItemParams objects

Detailed line items for the refund allocation. Use this for itemized refunds where you need to specify the exact amounts and accounts.

Show CreateCustomerRefundAllocationLineItemParams properties

amount

integer

required

Amount for this line item in cents.

account_identifier

AccountIdentifier object

The Account Identifier for this line item.

tags

array of TagKeyValue objects

Tags for this line item.

memo

string

Memo for this line item.

metadata

json object

Metadata for this line item.

reference_number

string

Reference number for this line item.

completed_at

ISO8601 timestamp

required

When the refund was completed.

refund_processing_fee

integer

Processing fee for the refund, in cents. Defaults to 0.

method

PaymentMethod enum

required

Method used to make the refund. Values can be: CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHER

processor

string

Processor used to make the refund, if any.

refunded_payment_fees

array of RefundedInvoicePaymentFeeInput objects

List of payment fees that were refunded as part of this refund.

Show RefundedInvoicePaymentFeeInput properties

account

AccountIdentifier object

required

The Account Identifier for the refunded fee.

description

string

Description of the fee being refunded.

amount

integer

required

Amount of the fee refund in cents.

tags

array of TagKeyValue objects

List of tags associated with this refund.

Show TagKeyValue properties

key

string

required

The tag’s key

value

string

required

The tag’s value

memo

string

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.

Example: Invoice with Dedicated Refunds

{
  "external_id": "invoice-123",
  "sent_at": "2024-04-02T09:02:00Z",
  "customer_external_id": "customer-456",
  "line_items": [
    {
      "product": "Widget Pro",
      "unit_price": 2500,
      "quantity": 4,
      "dedicated_refunds": [
        {
          "external_id": "refund-widget-1",
          "line_items": [
            {
              "amount": 1000,
              "account_identifier": {
                "type": "StableName",
                "stable_name": "CUSTOMER_REFUNDS"
              }
            }
          ],
          "completed_at": "2024-04-03T10:00:00Z",
          "method": "CREDIT_CARD",
          "processor": "RAINFOREST",
          "memo": "Partial (itemized) refund for damaged item"
        }
      ]
    }
  ],
  "payments": [
    {
      "external_id": "payment-123",
      "method": "CREDIT_CARD",
      "amount": 5000,
      "dedicated_refunds": [
        {
          "external_id": "refund-processing-fee",
          "completed_at": "2024-04-03T10:00:00Z",
          "method": "CREDIT_CARD",
          "processor": "RAINFOREST",
          "memo": "Full (simple) payment refund"
        }
      ]
    },
    {
      "external_id": "payment-xyz",
      "method": "CREDIT_CARD",
      "amount": 7000
    }
  ],
  "dedicated_refunds": [
    {
      "external_id": "refund-invoice-discount",
      "line_items": [
        {
          "amount": 250,
          "account_identifier": {
            "type": "StableName",
            "stable_name": "CUSTOMER_REFUNDS"
          }
        }
      ],
      "completed_at": "2024-04-03T10:00:00Z",
      "method": "CREDIT_CARD",
      "processor": "RAINFOREST",
      "memo": "Partial (itemized) refund for whole invoice"
    }
  ]
}

Businesses

Financial Activity

Accounting Reports

Platform Configuration

Activity Metrics

Quickbooks

Refund object

Creating Refunds

Simple Refunds

Itemized Refunds

Refund Object

Attributes

Refund Allocation Object

Refund Allocation Line Item Object

Refund Payment Object

Refunded Payment Fee Object

Simple Refund Creation Parameters

Itemized Refund Creation Parameters

Dedicated Refunds

Simple vs Itemized Dedicated Refunds

Create Dedicated Refund Parameters Object

Example: Invoice with Dedicated Refunds

Businesses

Financial Activity

Accounting Reports

Platform Configuration

Activity Metrics

Quickbooks

​Creating Refunds

​Simple Refunds

​Itemized Refunds

​Refund Object

​Attributes

​Refund Allocation Object

​Refund Allocation Line Item Object

​Refund Payment Object

​Refunded Payment Fee Object

​Simple Refund Creation Parameters

​Itemized Refund Creation Parameters

​Dedicated Refunds

​Simple vs Itemized Dedicated Refunds

​Create Dedicated Refund Parameters Object

​Example: Invoice with Dedicated Refunds

Creating Refunds

Simple Refunds

Itemized Refunds

Refund Object

Attributes

Refund Allocation Object

Refund Allocation Line Item Object

Refund Payment Object

Refunded Payment Fee Object

Simple Refund Creation Parameters

Itemized Refund Creation Parameters

Dedicated Refunds

Simple vs Itemized Dedicated Refunds

Create Dedicated Refund Parameters Object

Example: Invoice with Dedicated Refunds