Refund object

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

string

required

Unique identifier for the refund.

string

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

integer

required

Amount refunded to the customer in cents.

string

required

Status of the refund.

ISO8601 timestamp

required

Time when the refund was completed.

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.

array of RefundAllocation objects

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

array of RefundPayment objects

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

array of Payout objects

Payouts associated with this refund.

Array of Tags

Tags associated with the 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 refund.

json object

Arbitrary metadata you can include with the refund.

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.

string

ID of the invoice this allocation is associated with.

integer

required

Amount of the allocation in cents.

array of RefundAllocationLineItem objects

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

string

External ID of the invoice this allocation is associated with.

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.

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.

string

ID of the invoice payment this allocation is associated with.

string

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

Customer object

The Customer associated with this refund allocation.

Array of Tags

Tags associated with the 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 refund allocation.

json object

Arbitrary metadata you can include with the refund allocation.

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.

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 ledger 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.

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.

string

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

integer

required

Amount refunded to the customer in cents.

integer

Fee paid by the business to make 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 RefundedPaymentFee objects

Refunded payment fees associated with the refund payment. See Refunded Payment Fee Object for details.

Array of Tags

Tags associated with the 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 refund payment.

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.

AccountIdentifier object

required

Identifier of the ledger account for the refunded payment fee.

string

Description of the fee that the refunded payment fee refunds.

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.

string

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

ISO8601 timestamp

required

When the refund was completed and paid.

string

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

string

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

string

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

string

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

string

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

string

The external ID of the invoice 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 refund. Tags are key-value pairs that can be used to categorize and filter 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 refund.

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.

string

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

integer

required

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

ISO8601 timestamp

required

When the refund was completed.

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

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 invoice this allocation targets.

string

External ID of the invoice this allocation targets.

string

ID of the invoice line item this allocation targets.

string

External ID of the invoice line item this allocation targets.

string

ID of the invoice payment this allocation targets.

string

External ID of the invoice payment this allocation targets.

string

ID of the customer this allocation targets.

string

External ID of the customer this allocation targets.

array of TagKeyValue objects

Tags for this allocation.

string

Memo for this allocation.

json object

Metadata for this allocation.

array of RefundPaymentParams objects

required

The payment methods and amounts used to process the refund.

Show RefundPaymentParams properties

string

External identifier for the payment.

integer

required

Amount refunded to the customer 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 RefundedPaymentFeeInput objects

Fees refunded as part of this payment.

array of TagKeyValue objects

Tags for this payment.

string

Memo for this payment.

json object

Metadata for this payment.

string

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

array of TagKeyValue objects

Tags to apply to the refund. Tags are key-value pairs that can be used to categorize and filter 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 refund.

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

string

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

AccountIdentifier object

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

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

integer

required

Amount for this line item in cents.

AccountIdentifier object

The Account Identifier for this line item.

array of TagKeyValue objects

Tags for this line item.

string

Memo for this line item.

json object

Metadata for this line item.

string

Reference number for this line item.

ISO8601 timestamp

required

When the refund was completed.

integer

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

PaymentMethod enum

required

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

string

Processor used to make the refund, if any.

array of RefundedInvoicePaymentFeeInput objects

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

Show RefundedInvoicePaymentFeeInput properties

AccountIdentifier object

required

The Account Identifier for the refunded fee.

string

Description of the fee being refunded.

integer

required

Amount of the fee refund in cents.

array of TagKeyValue objects

Tags to apply to the refund. Tags are key-value pairs that can be used to categorize and filter 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

Any text you would like to associate with the refund.

json object

Arbitrary metadata you can include with the refund.

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

Remove payout tags List refunds

⌘I

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

​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