Refunds

Refunds let you return money for a paid order without rewriting the sale that already happened. They are line-item based, asynchronous, and tied to the customer’s original payment method.

Use MCP before refunding

An authenticated AI agent can inspect the paid order and render a compact order card before your server creates the refund. Refund creation and cancellation still use the Refunds API.

MCP tools: get_order or render_order_card

Use this page to understand the refund product. Use the Refunds API reference for the exact request contract, response shape, and errors.

What refunds solve

A refund is the right tool when money has already been collected and some or all of it needs to go back to the customer.

Use refunds for:

• returned items;
• damaged, missing, or not-as-described items;
• duplicate or mistaken charges;
• order cancellations after payment;
• fraud-related reversals; and
• support adjustments tied to a paid order.

Do not edit a paid order to represent returned money. The order remains the record of the original sale. The refund becomes the record of the money sent back.

The refund model

Refunds are rooted in orders, but they have their own lifecycle.

Object	Role
Order	Original paid transaction.
Order line item	Specific part of the sale being refunded.
Refund	Durable request to return money for one or more order line items.
Refund line item	Allocation of one refund amount to one order line item.
Balance transaction	Financial evidence for reconciliation after money moves.

The API does not accept a refund destination or payment ID. Inttegro resolves those from the paid order so the money goes back through the original payment method.

Full and partial refunds

A full refund means you include every refundable line item for its remaining refundable amount. A partial refund returns only selected line items, or less than the remaining amount on those line items.

Line-item allocation is the key design choice. It lets support and finance answer exactly what was refunded later:

• one returned product from a multi-item order;
• shipping or fees associated with a return;
• a partial goodwill adjustment; or
• the entire paid order.

Each refund line amount must be positive, use the same currency as the original order line item, and fit within that line item’s remaining refundable amount. If a line has already been partially refunded, only the remaining refundable amount is available for later refunds.

Eligibility

Refund creation succeeds only when the order, line items, and merchant balance can support it.

The usual checks are:

• the order is paid;
• the order has a customer and an original payment method;
• every order_line_item_id belongs to that order;
• each order line item appears at most once in the request;
• the requested amounts are positive and within what remains refundable;
• the merchant balance is ready and sufficient; and
• the request stays within the configured order line-item limit, currently 64 by default.

The current endpoint expects paid amounts that can be allocated exactly to supported refundable line types. Orders containing discounts, donations, subscriptions, or taxes are not currently refundable through this endpoint.

Reasons and evidence

Refunds require an overall reason. Use line-level reasons only when different items in the same refund need different explanations.

Choose the standard reason that best fits the case. Use custom only when the standard reasons are not specific enough, and include concise reason_details so the decision is understandable later.

Good refund records help three teams:

• support can explain what happened to the customer;
• finance can reconcile the returned amount; and
• operations can detect product, fulfillment, or fraud patterns.

How refunds affect balances and payouts

Refunds affect two things at once: the order line item’s remaining refundable capacity and the merchant balance that could otherwise be paid out.

When Inttegro accepts a refund, it records a pending refund and reserves the needed capacity. That reservation prevents the same paid line item from being refunded twice, and prevents the same merchant funds from being selected for a payout while the refund is still unresolved.

Read the effect by lifecycle:

Refund state	Balance effect	Payout effect
pending	Refund capacity and merchant funds are reserved for the refund. A balance snapshot may show less available balance, refund activity, or reserved funds depending on timing.	Payout selection should not use the funds needed for that refund.
processing	The reservation is already claimed for execution.	Treat those funds as unavailable for new payouts.
succeeded	Balance transactions become the reconciliation evidence for the returned money.	The refunded funds are no longer available for payout.
failed	Inspect the refund and balance transaction state before retrying. Do not assume capacity was restored without checking the current refund record.	Do not schedule a replacement payout from assumptions; verify current balance and payout eligibility first.
canceled	If cancellation happens before processing claims the refund, Inttegro releases the merchant balance hold and restores the reserved refundable capacity.	Released funds can be considered again by future payout selection if they satisfy the normal payout rules. They are not retroactively added to payouts already scheduled or executing.

This is why a payout can be lower than the dashboard number an operator expected. Between the time someone checks balance and the time payout selection runs, refunds can reserve or consume funds. Existing open payouts can also claim funds first.

For operations, compare four records before explaining a difference: the refund, the current balance snapshot, related balance transactions, and any open or recent payouts for the same currency.

See How payouts use your balance for whole-transaction selection examples and how to reconcile a payout after a refund reduces one of its source payments.

Lifecycle

Refund processing is asynchronous.

Status	Meaning	What to do
pending	The refund was accepted and is waiting for processing.	Store the refund ID and monitor it.
processing	Execution has started.	Do not cancel; wait for a terminal state.
succeeded	Money was returned successfully.	Notify the customer and reconcile.
failed	The refund did not complete.	Inspect the failure and decide whether to retry with a new, intentional request.
canceled	The refund was canceled before processing claimed it.	Treat it as stopped; no money should move for that refund.

Poll Lookup a refund when your workflow needs the final result. Lifecycle timestamps are omitted until the transition happens.

Create and cancel safely

Use Create a refund for new integrations. POST /orders/refund is a compatibility alias for the same behavior; avoid switching between both paths for one logical refund.

Cancellation is narrow by design. Only a pending refund without a processing attempt or processing timestamp can be canceled. After processing starts, use the final refund status and support workflow instead of trying to undo it.

Always use stable idempotency keys for create and cancel requests. If the network fails after submission, retry with the same key and the same body so Inttegro can return the original result instead of creating a second logical refund.

Where MCP helps

MCP is useful before the money-moving step:

• look up the original order;
• summarize payment, fulfillment, and total state;
• render a compact order card for review; and
• keep raw customer contact details out of the operator prompt.

MCP does not create or cancel refunds. Keep those actions in your trusted backend or dashboard workflow.

Implementation checklist

Before using refunds in production:

• expose order line-item IDs in support tooling;
• show the remaining refundable amount per line item;
• require a reason before submission;
• calculate refund amounts in integer minor units;
• use idempotency keys;
• store the returned rf_... refund ID;
• poll lookup until terminal state when your workflow needs confirmation;
• notify the customer only from an accepted or final state that matches your policy; and
• reconcile successful refunds through balance transactions.

Related resources

• Refunds API reference - Exact refund operation contract.
• Create a refund - Canonical refund creation endpoint.
• Cancel a refund - Stop a refund before processing claims it.
• Lookup a refund - Refresh refund lifecycle state.
• Orders - Understand the original sale being adjusted.
• Balances - Understand aggregate balance effects.
• Balance transactions - Understand refund-linked money movement.