---
title: "Refunds"
description: "Return money for specific paid order line items through the customer's original payment method."
canonical: "https://studio.inttegro.com/api/refunds"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 555
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_refund_options","get_refund","create_refund"]
focused_slices: ["https://studio.inttegro.com/machine/python/api/refunds/create.md"]
estimated_tokens: 9386
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** This reference defines line-item refund creation, lookup, cancellation, paging, status, and failure data. A “wire-only” request field is not a verified native SDK member.

For refund creation only, start with the [focused create reference](https://studio.inttegro.com/machine/python/api/refunds/create.md). The full reference remains authoritative for lookup, cancellation, and failure interpretation.

### Five questions

#### Q1. Which amounts can be refunded?

Refund paid order line items, not an arbitrary order amount. Read current order or refund state, use each line once, and keep each allocation within its remaining refundable amount and original currency.

#### Q2. What must be preserved when creating the refund?

Supply the paid order ID, a required overall reason, and one to 64 line-item allocations. If the result is uncertain, repeat only the identical payload with the same [idempotency key](https://studio.inttegro.com/machine/python/api/idempotency.md).

#### Q3. What proves that money was returned?

A create response starts in pending state. Save the refund ID and [look it up](https://studio.inttegro.com/machine/python/api/refunds.md#lookup-a-refund) until it is succeeded; request acceptance, processing, and a browser return do not prove settlement.

#### Q4. How should cancellation or failure be interpreted?

Cancellation is available only while pending. For a terminal failure, read the documented failure reason and retryability indicator before deciding whether a new intentional refund is appropriate; see [Handling refund failures](https://studio.inttegro.com/machine/python/api/refunds.md#handling-refund-failures).

#### Q5. Which MCP abilities help, and what is their boundary?

With an authenticated MCP connection, [`get_refund_options`](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_refund_options) checks line availability, [`get_refund`](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_refund) reconciles status, and [`create_refund`](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#create_refund) requires exact user confirmation. This reference remains the contract source.

## Document content

# Refunds

Refunds return all or part of a paid order to the customer's original payment method. Use this API to create a refund, follow its progress, cancel it before processing begins, or browse previous refunds.

For an explanation of refund eligibility, lifecycle, and effects on balances and payouts, read the [Refunds product guide](https://studio.inttegro.com/machine/python/products/refunds.md). This page is the endpoint reference.

Create new refunds through `POST /refunds/create`.

## Preserve refund allocation and recovery semantics

- **Refund paid order lines, not an arbitrary standalone amount.** Every
  allocation must identify a line item from the selected order, and a line item
  can appear only once in the request. Verify remaining refundable amounts from
  current order or refund state before constructing allocations.
- **Creation starts an asynchronous lifecycle.** Preserve the returned refund
  ID and use [Lookup a refund](#lookup-a-refund) until the state is terminal.
  Do not interpret request acceptance as money already returned.
- **Cancellation is a narrow transition.** It is available only while the
  refund remains pending. An already canceled refund can be treated as the
  desired result when the same idempotency key and request body are reused.
- **Let the public error direct retries.** Repeat a transient failure only when
  [`error.fix_code`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund)
  recommends it, preserving the endpoint, payload, and [idempotency
  key](https://studio.inttegro.com/machine/python/api/idempotency.md). Read [Refunds](https://studio.inttegro.com/machine/python/products/refunds.md) for the balance and
  payout effects.

## The refund object

A refund records the amounts requested against an order's line items, why they were returned, where the money is settled, and the refund's current status. Payment-method refunds begin as [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING) and then become [`inttegro.refund.Status.PROCESSING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PROCESSING), [`inttegro.refund.Status.SUCCEEDED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.SUCCEEDED), or [`inttegro.refund.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.FAILED). Offline refunds begin as [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING) and become [`inttegro.refund.Status.SUCCEEDED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.SUCCEEDED) only after a trusted operator records the settlement. A refund canceled before processing begins has a [`inttegro.refund.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.CANCELED) status.

Order responses may include the same objects in [`order.refunds`](https://python.inttegro.dev/v12.0.0/inttegro/order.html#Order), with the newest refund first. Optional properties and lifecycle timestamps appear when they have a value.

Each refund line includes an immutable

[`refund.line_items[].order_line_item`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) snapshot when the
originating order can be resolved. Treat it as a union selected by
[`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund):
`'product'`,
`'fee'`, or
`'shipping'`.
Match the allocation to the order through `order_line_item.id`.
For product lines, `order_line_item.product.id` links to the
source catalog product; inline products omit that product ID.

### Properties

- [`cancel_reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

  Explanation supplied when the refund was canceled. Omitted when cancellation
  did not include a reason. This free-form text is separate from the
  [`refund.reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) recorded when the refund was created and
  the [`refund.failure.reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) returned after a terminal
  failure.

- [`canceled_at`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `timestamp`

  When the refund entered the [`inttegro.refund.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.CANCELED) state. Omitted otherwise.

- [`created_at`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `timestamp`

  When the refund was created.

- [`custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

  Your metadata, returned as string values. Omitted when empty.

- [`failure`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund)

  Sanitized terminal failure information. Present only when status is failed.

  - [`failure.detail`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

    Safe explanation of what prevented the refund from completing.

  - [`failure.reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

    Stable failure category. The possible values follow.

  - [`failure.retryable`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `boolean`

    Whether you may be able to resolve the condition before creating a new, intentional refund. It never means that an uncertain request should be repeated blindly.

- [`failed_at`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `timestamp`

  When the refund entered the
  [`inttegro.refund.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.FAILED) state.
  Omitted otherwise.

- [`id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

  Unique refund identifier with the `rf_` prefix.

- [`line_items`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund)

  Immutable allocations describing how much is refunded for each order line item.

  - [`line_items.id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

    Server-generated refund line-item ID with the rli\_ prefix.

  - [`line_items.order_line_item`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

    Immutable snapshot of the original order line. Use order\_line\_item.id to match the refund allocation to the order. Discriminate on [`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) before reading the product, fee, or shipping branch. Omitted when the originating order cannot be resolved.

    - [`line_items.order_line_item.fee`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

      Fee details captured on the order. Present only when [`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) is `'fee'` .

      - [`line_items.order_line_item.fee.description`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Fee description captured on the order.

      - [`line_items.order_line_item.fee.label`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Fee label captured on the order.

    - [`line_items.order_line_item.id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

      Original order line-item ID with the oli\_ prefix.

    - [`line_items.order_line_item.product`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

      Product details captured on the order. Present only when [`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) is `'product'` .

      - [`line_items.order_line_item.product.id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Source catalog product ID with the prod\_ prefix. Omitted for inline products.

      - [`line_items.order_line_item.product.name`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Product name captured on the order.

    - [`line_items.order_line_item.quantity`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `integer`

      Quantity captured on the order. Present only when [`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) is `'product'` .

    - [`line_items.order_line_item.shipping`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

      Shipping details captured on the order. Present only when [`refund.line_items[].order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) is `'shipping'` .

      - [`line_items.order_line_item.shipping.description`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Shipping description captured on the order.

      - [`line_items.order_line_item.shipping.label`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

        Shipping label captured on the order.

    - [`line_items.order_line_item.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

      `'product'` , `'fee'` , or `'shipping'` .

  - [`line_items.original_amount_paid`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

    Amount originally paid for this order line allocation.

    - [`line_items.original_amount_paid.currency`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

      Lowercase currency code.

    - [`line_items.original_amount_paid.value`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `integer`

      Positive amount in the smallest currency unit.

  - [`line_items.reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

    Independent reason for refunding this line. Omitted when not provided.

  - [`line_items.reason_details`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

    Line-specific explanation. Omitted when not provided.

  - [`line_items.refund_amount`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

    Amount returned for this line.

    - [`line_items.refund_amount.currency`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

      Lowercase currency code.

    - [`line_items.refund_amount.value`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `integer`

      Positive amount in the smallest currency unit.

- [`order_id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

  Paid order covered by this refund, with the `or_` prefix.

- [`processing_at`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `timestamp`

  When refund processing began. Omitted until processing starts.

- [`reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

  Overall refund reason:
  [`inttegro.refund.Reason.CUSTOM`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.CUSTOM),
  [`inttegro.refund.Reason.DUPLICATE`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.DUPLICATE),
  [`inttegro.refund.Reason.FRAUDULENT`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.FRAUDULENT),
  [`inttegro.refund.Reason.ITEM_DAMAGED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_DAMAGED),[`inttegro.refund.Reason.ITEM_NOT_AS_DESCRIBED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_AS_DESCRIBED), [`inttegro.refund.Reason.ITEM_NOT_RECEIVED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_RECEIVED),
  [`inttegro.refund.Reason.ITEM_RETURNED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_RETURNED),[`inttegro.refund.Reason.ORDER_CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ORDER_CANCELED), or [`inttegro.refund.Reason.REQUESTED_BY_CUSTOMER`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.REQUESTED_BY_CUSTOMER).

- [`reason_details`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

  Overall explanation. Omitted when not provided.

- [`reference`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

  Your reconciliation reference. Omitted when not provided.

- [`settlement`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund)

  Immutable destination captured when the refund is created. The required type discriminator is offline or payment\_method.

  - [`settlement.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

    offline means the order was paid outside Inttegro. payment\_method means the refund returns to the original payment method used for the order.

  - [`settlement.payment_method`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

    Present only when type is payment\_method. This is a caller-safe immutable snapshot, not the mutable payment-method management object.

    - [`settlement.payment_method.id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

      Public original payment-method ID with the pm\_ prefix.

    - [`settlement.payment_method.type`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

      mobile\_money or bank\_account.

    - [`settlement.payment_method.mobile_money`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

      Present only for mobile\_money. Includes network, last4, and account\_number masked as \*\*\*\*1234.

    - [`settlement.payment_method.bank_account`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `object`

      Present only for bank\_account. Its ghana\_bank\_account contains last4 and account\_number masked as \*\*\*\*1234.

- [`status`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `enum`

  Current state:
  [`inttegro.refund.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.CANCELED),
  [`inttegro.refund.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.FAILED),
  [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING),
  [`inttegro.refund.Status.PROCESSING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PROCESSING), or
  [`inttegro.refund.Status.SUCCEEDED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.SUCCEEDED).

- [`succeeded_at`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `timestamp`

  When the refund entered the [`inttegro.refund.Status.SUCCEEDED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.SUCCEEDED) state. Omitted otherwise.

- [`total`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund)

  Sum of the requested line-item refund amounts.

  - [`total.currency`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `string`

    Lowercase currency code.

  - [`total.value`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) — `integer`

    Positive amount in the smallest currency unit.

> **Warning:**
>
> The settlement snapshot never contains a full phone or bank-account number,
> provider identifiers, fingerprints, credentials, verification request IDs, or
> custom data. Store it with the refund as historical display evidence; use
> Payment Methods endpoints for current management state.

#### Failure reason values

- `'amount_not_supported'`— The
  requested refund amount is not supported.
- `'insufficient_balance'`— The
  available balance cannot fund the refund.
- `'original_payment_method_unavailable'`
  — The original payment method cannot receive the refund.
- `'original_payment_not_refundable'`
  — The original payment cannot be refunded.
- `'refund_declined'`— The refund
  was declined.
- `'refund_not_permitted'`— The
  refund is not permitted.
- `'refund_not_supported'`— This
  refund is not supported.
- `'temporarily_unavailable'`—
  Refund processing is temporarily unavailable.
- `'unknown'`— Inttegro could not
  safely classify the failure. Do not retry unless support advises you to.

## Create a refund

Return all or part of one or more paid order line items. Inttegro sends each amount back through the payment method used for the order. Processing happens asynchronously, so every new refund begins in [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING) status.

Before creating the refund:

- Read the order to obtain its line-item IDs and current refundable amounts.
- Include each line item once, using the same currency and no more than its remaining refundable amount.
- Reuse the same idempotency key and request body if the result of a request is uncertain.

### Request attributes

- [`custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.custom_data) — `CustomData`

  Optional metadata for reconciliation. The object can contain at most 25 KB of JSON, and each key can contain at most 256 characters. Stored values are returned as strings.

- [`line_items`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.line_items) — `list[refund.CreateLineItemInput]` — required

  One to 64 order line-item allocations to refund. Each order line item can appear only once.

  - [`line_items.order_line_item_id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateLineItemInput.order_line_item_id) — `str` — required

    Order line-item ID with the oli\_ prefix. It must belong to [`order_id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.order_id).

  - [`line_items.reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateLineItemInput.reason) — `RefundReasonInput`

    Optional reason specific to this line. It is independent of the overall refund reason. Allowed values: [`inttegro.refund.Reason.CUSTOM`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.CUSTOM), [`inttegro.refund.Reason.DUPLICATE`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.DUPLICATE), [`inttegro.refund.Reason.FRAUDULENT`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.FRAUDULENT), [`inttegro.refund.Reason.ITEM_DAMAGED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_DAMAGED), [`inttegro.refund.Reason.ITEM_NOT_AS_DESCRIBED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_AS_DESCRIBED), [`inttegro.refund.Reason.ITEM_NOT_RECEIVED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_RECEIVED), [`inttegro.refund.Reason.ITEM_RETURNED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_RETURNED), [`inttegro.refund.Reason.ORDER_CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ORDER_CANCELED), or [`inttegro.refund.Reason.REQUESTED_BY_CUSTOMER`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.REQUESTED_BY_CUSTOMER).

  - [`line_items.reason_details`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateLineItemInput.reason_details) — `str`

    Optional line-specific explanation, up to 2,048 characters. Requires a line-level reason and is required when that reason is [`inttegro.refund.Reason.CUSTOM`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.CUSTOM).

  - [`line_items.refund_amount`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateLineItemInput.refund_amount) — `money.AmountParams` — required

    Positive amount to refund for this line. It cannot exceed the remaining refundable amount.

    - [`line_items.refund_amount.currency`](https://python.inttegro.dev/v12.0.0/inttegro/money.html#AmountParams.currency) — `Currency` — required

      Currency code. It is normalized to lowercase and must match the order line item.

    - [`line_items.refund_amount.value`](https://python.inttegro.dev/v12.0.0/inttegro/money.html#AmountParams.value) — `int` — required

      Amount in the smallest currency unit; minimum 1.

- [`order_id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.order_id) — `str` — required

  Paid order to refund, using the `or_` ID returned by Inttegro.

- [`reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.reason) — `RefundReasonInput` — required

  Overall refund reason. Allowed values: [`inttegro.refund.Reason.CUSTOM`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.CUSTOM), [`inttegro.refund.Reason.DUPLICATE`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.DUPLICATE),
  [`inttegro.refund.Reason.FRAUDULENT`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.FRAUDULENT), [`inttegro.refund.Reason.ITEM_DAMAGED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_DAMAGED), [`inttegro.refund.Reason.ITEM_NOT_AS_DESCRIBED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_AS_DESCRIBED),
  [`inttegro.refund.Reason.ITEM_NOT_RECEIVED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_NOT_RECEIVED), [`inttegro.refund.Reason.ITEM_RETURNED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ITEM_RETURNED), [`inttegro.refund.Reason.ORDER_CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.ORDER_CANCELED), or
  [`inttegro.refund.Reason.REQUESTED_BY_CUSTOMER`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.REQUESTED_BY_CUSTOMER).

- [`reason_details`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.reason_details) — `str`

  Optional overall explanation, up to 2,048 characters. Required when [`reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.reason) is [`inttegro.refund.Reason.CUSTOM`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Reason.CUSTOM).

- [`reference`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#CreateRequest.reference) — `str`

  Optional non-empty reconciliation reference, up to 256 characters.

### Response

Returns the new refund in [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING) status. Save its [`refund.id`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) and use [Lookup a refund](#lookup-a-refund) when you need its latest status.

**Request — POST /refunds/create**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.refunds.create(inttegro.refund.CreateRequest(
  custom_data=inttegro.CustomData({
    "warehouse": "accra",
  }),
  line_items=[
    inttegro.refund.CreateLineItemInput(
      order_line_item_id="oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
      reason=inttegro.refund.Reason.ITEM_DAMAGED,
      reason_details="Packaging was crushed.",
      refund_amount=inttegro.money.AmountParams(
        currency=inttegro.money.Currency.GHS,
        value=2500,
      ),
    ),
    inttegro.refund.CreateLineItemInput(
      order_line_item_id="oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
      refund_amount=inttegro.money.AmountParams(
        currency=inttegro.money.Currency.GHS,
        value=1000,
      ),
    ),
  ],
  order_id="or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
  reason=inttegro.refund.Reason.REQUESTED_BY_CUSTOMER,
  reason_details="Customer returned part of the order.",
  reference="return_1042",
),
    idempotency_key="refund-return-1042")
```

```json
{
  "refund": {
    "created_at": "2026-08-30T12:00:00Z",
    "custom_data": {
      "warehouse": "accra"
    },
    "id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
    "line_items": [
      {
        "id": "rli_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
        "order_line_item": {
          "id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
          "product": {
            "id": "prod_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
            "name": "Canvas backpack"
          },
          "quantity": 1,
          "type": "product"
        },
        "original_amount_paid": {
          "currency": "ghs",
          "value": 10000
        },
        "reason": "item_damaged",
        "reason_details": "Packaging was crushed.",
        "refund_amount": {
          "currency": "ghs",
          "value": 2500
        }
      },
      {
        "id": "rli_ZYXWVUTSRQPONMLKJIHGFEDCBAabcdefghijklmn",
        "order_line_item": {
          "fee": {
            "description": "Gift wrapping service.",
            "label": "Gift wrapping"
          },
          "id": "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
          "type": "fee"
        },
        "original_amount_paid": {
          "currency": "ghs",
          "value": 5000
        },
        "refund_amount": {
          "currency": "ghs",
          "value": 1000
        }
      }
    ],
    "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
    "reason": "requested_by_customer",
    "reason_details": "Customer returned part of the order.",
    "reference": "return_1042",
    "settlement": {
      "payment_method": {
        "id": "pm_xyz789",
        "mobile_money": {
          "account_number": "****7831",
          "last4": "7831",
          "network": "mtn"
        },
        "type": "mobile_money"
      },
      "type": "payment_method"
    },
    "total": {
      "currency": "ghs",
      "value": 3500
    },
    "status": "pending"
  }
}
```

## Cancel a refund

Cancel a refund while its status is [`inttegro.refund.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PENDING), before Inttegro begins processing it. Cancellation releases the balance reserved for the refund and restores the affected order lines' refundable amounts.

A refund cannot be canceled once it is [`inttegro.refund.Status.PROCESSING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PROCESSING), [`inttegro.refund.Status.SUCCEEDED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.SUCCEEDED), or [`inttegro.refund.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.FAILED). Repeating this operation for an already canceled refund returns the same refund, making retries safe when you reuse the same idempotency key and request body.

### Request attributes

- `reason` — `string` — wire-only

  Optional explanation for canceling the refund. Inttegro removes leading
  and trailing whitespace; when supplied, the remaining text must contain
  1–2,048 characters. It is returned as [`refund.cancel_reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund). An idempotent repeat preserves the explanation recorded by the first
  successful cancellation.

- `refund_id` — `string` — required — wire-only

  Refund to cancel, with the `rf_` prefix.

- `request_meta` — wire-only

  Optional body-level idempotency key. Prefer the Idempotency-Key header for new integrations.

  - `request_meta.idempotency_key` — `string` — wire-only

    Stable retry key from 1 through 255 characters. It must match the Idempotency-Key header when both are present.

### Response

Returns the refund in [`inttegro.refund.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.CANCELED) status. When a reason was supplied, the response includes [`refund.cancel_reason`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund); the selected SDK view shows its native property name.

**Request — POST /refunds/cancel**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.refunds.cancel(
    "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
    idempotency_key="cancel-refund-return-1042",
    reason="Customer asked us to stop the return."
)
```

## Lookup a refund

Retrieve a refund's current status and line-item amounts. Use this after creating or canceling a refund, or when helping a customer with a return.

### Request attributes

- `refund_id` — `string` — required — wire-only

  Refund to retrieve, with the `rf_` prefix.

### Response

Returns the requested refund.

**Request — POST /refunds/lookup**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.refunds.lookup("$INTTEGRO_REFUND_ID")
```

## List refunds

Browse refunds from newest to oldest. Use this endpoint to build refund history, customer-service, and reconciliation views.

Pages are one-based. [`page_size`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#PageRequest.page_size) defaults to `256`, and the response's [`page.size`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) is the number of refunds actually returned. An empty page is successful and contains [`page.size`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) set to `0` and an empty [`page.refunds`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) collection.

### Request attributes

- [`page_number`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#PageRequest.page_number) — `int` — required

  Page to retrieve, from `1` through `10`.

- [`page_size`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#PageRequest.page_size) — `int`

  Maximum refunds to request, from `1` through `256`. Defaults to `256`.

### Response

Returns the page number, number of results, and a [`page.refunds`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) array. An empty page returns an empty [`page.refunds`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) collection and [`page.size`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Page) set to `0`.

**Request — POST /refunds/page**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.refunds.page(inttegro.refund.PageRequest(
  page_number=1,
  page_size=20,
))
```

```json
{
  "page": {
    "number": 1,
    "refunds": [
      {
        "created_at": "2026-08-30T12:00:00Z",
        "id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
        "line_items": [
          {
            "id": "rli_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
            "order_line_item": {
              "id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
              "product": {
                "name": "Custom tailoring"
              },
              "quantity": 1,
              "type": "product"
            },
            "original_amount_paid": {
              "currency": "ghs",
              "value": 10000
            },
            "refund_amount": {
              "currency": "ghs",
              "value": 2500
            }
          }
        ],
        "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
        "reason": "item_returned",
        "settlement": {
          "type": "offline"
        },
        "total": {
          "currency": "ghs",
          "value": 2500
        },
        "status": "pending"
      }
    ],
    "size": 1
  }
}
```

## Handling refund failures

Request errors and terminal refund failures are different. A request rejected
before a refund is created uses the standard `error` envelope.
An accepted refund that later reaches

[`inttegro.refund.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.FAILED) includes
[`refund.failure`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund).

Use the reason to choose the next step:

- `'amount_not_supported'`—
  Retrieve the current order and correct the amount before creating a new
  refund.
- `'insufficient_balance'`—
  Restore sufficient available balance before creating a new refund.
- `'original_payment_method_unavailable'`
  — Do not submit the same refund again. Contact support if another return route
  is needed.
- `'original_payment_not_refundable'`
  — Do not submit the same refund again. Contact support if the customer still
  needs another return route.
- `'refund_declined'`
  — Read [`refund.failure.detail`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) before deciding whether the
  condition can be corrected.
- `'refund_not_permitted'`—
  Retrieve the current order and refund state, then correct the eligibility
  issue before creating a new refund.
- `'refund_not_supported'`— Do not
  submit the same refund again. Contact support if another return route is
  needed.
- `'temporarily_unavailable'`—
  Wait before creating a new refund, and first confirm that the existing refund
  is terminal.
- `'unknown'`— Treat the failure
  as non-retryable unless support advises otherwise.
- When [`refund.failure.retryable`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Refund) is `true`, resolve the reported condition before creating a new, intentional refund. It is not permission to repeat a refund whose status is still [`inttegro.refund.Status.PROCESSING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PROCESSING).
- A timeout or uncertain provider outcome remains [`inttegro.refund.Status.PROCESSING`](https://python.inttegro.dev/v12.0.0/inttegro/refund.html#Status.PROCESSING); it is never represented as a terminal failure reason.

## Related resources

- [Refunds product guide](https://studio.inttegro.com/machine/python/products/refunds.md) — Understand eligibility, lifecycle, balances, and payouts.
- [Lookup an order](https://studio.inttegro.com/machine/python/api/orders.md#lookup-an-order) — Read the paid order and its line-item IDs before creating a refund.
- [Errors](https://studio.inttegro.com/machine/python/api/errors.md) — Handle Inttegro API errors consistently.