--- title: "Refunds" description: "Return money after a paid order while keeping the original sale and audit trail intact." canonical: "https://studio.inttegro.com/products/refunds" format: inttegro-machine-docs/v1 language: "cURL" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/curl/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: 576 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "curated" recommended_mcp_tools: ["get_refund_options","create_refund","get_refund"] estimated_tokens: 3904 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Return money against paid order line items without changing the original sale; a created refund is asynchronous and must be looked up before reporting success. ### Five questions #### Q1. Which sale and payment does a refund target? Use a paid order and its eligible order line-item IDs. The [Refunds API](https://studio.inttegro.com/machine/curl/api/refunds.md#create-a-refund) derives the destination and original payment from the paid order; do not supply an unrelated payment or destination ID. #### Q2. How is a full or partial amount specified? Allocate positive amounts to distinct order line items, within each line's remaining refundable capacity and original currency. For a full refund, include every refundable line for its remaining amount. See [full and partial refunds](https://studio.inttegro.com/machine/curl/products/refunds.md#full-and-partial-refunds). #### Q3. What does an accepted refund do before it succeeds? It reserves refundable capacity and merchant funds so the same line or funds cannot be selected twice. A pending or processing result is not returned money; [look up the refund](https://studio.inttegro.com/machine/curl/api/refunds.md#lookup-a-refund) for a terminal outcome and reconcile balance transactions. #### Q4. Can a failed or processing refund simply be retried? No. Read the public failure reason, detail, and retryable flag after a terminal failure. An uncertain provider outcome remains processing; reuse a stable idempotency key on uncertain create responses. [Cancellation](https://studio.inttegro.com/machine/curl/api/refunds.md#cancel-a-refund) is only for a still-pending refund. #### Q5. Can MCP create or cancel one? Yes, with an authenticated client and exact confirmation. [create_refund](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#create_refund) refreshes refundable options and confirms every amount and reason; [cancel_refund](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#cancel_refund) attempts cancellation of a still-pending refund. [get_refund](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#get_refund) checks current state; unattended flows use the trusted backend and [Refunds API](https://studio.inttegro.com/machine/curl/api/refunds.md). ## Document content # 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. > Mcp Guide Callout is interactive content. Use the canonical page to view it. Use this page to understand the refund product. Use the [Refunds API reference](https://studio.inttegro.com/machine/curl/api/refunds.md) 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` | Refund execution has started and the reservation is no longer cancellable. | 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` | Read the sanitized `failure.reason`, `failure.detail`, and `failure.retryable` values before creating a new refund. | Do not schedule a replacement payout from assumptions; verify current balance and payout eligibility first. | | `canceled` | If cancellation happens before refund execution starts, 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 allocate 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](https://studio.inttegro.com/machine/curl/guides/understand-payouts.md) for partial-allocation examples and how to reconcile a payout after a refund uses some of a source payment. ## 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 sanitized failure. Create a new refund only after resolving a retryable condition. | | `canceled` | The refund was canceled before execution started. | Treat it as stopped; no money should move for that refund. | Poll [Lookup a refund](https://studio.inttegro.com/machine/curl/api/refunds.md#lookup-a-refund) when your workflow needs the final result. Lifecycle timestamps are omitted until the transition happens. Failed refunds include a caller-safe `failure` object. Its `reason` is a stable public category rather than a provider code, and `unknown` is the fail-closed fallback for an unclassified internal failure. Raw provider messages, routing details, credentials, and risk signals are never returned. An uncertain provider outcome stays `processing` while Inttegro reconciles it; it is not reported as a failed refund. ## Create and cancel safely Use [Create a refund](https://studio.inttegro.com/machine/curl/api/refunds.md#create-a-refund) for refund integrations. 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 can help with the full assisted refund workflow: - look up the paid order and current refundable options; - create an asynchronous line-item refund after confirming the exact amount for each line, any line-level reasons, and the required overall reason; - look up the refund to determine its current state; and - attempt cancellation only while the refund is still pending, after confirming its current amount, order, and reason. For unattended integrations, use the [Refunds API reference](https://studio.inttegro.com/machine/curl/api/refunds.md) from your trusted backend. An MCP action still requires its own confirmation; a pending result is not proof that money has returned. ## 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](https://studio.inttegro.com/machine/curl/api/refunds.md) - Exact refund operation contract. - [Create a refund](https://studio.inttegro.com/machine/curl/api/refunds.md#create-a-refund) - Canonical refund creation endpoint. - [Cancel a refund](https://studio.inttegro.com/machine/curl/api/refunds.md#cancel-a-refund) - Stop a refund before execution starts. - [Lookup a refund](https://studio.inttegro.com/machine/curl/api/refunds.md#lookup-a-refund) - Refresh refund lifecycle state. - [Orders](https://studio.inttegro.com/machine/curl/products/orders.md) - Understand the original sale being adjusted. - [Balances](https://studio.inttegro.com/machine/curl/guides/understand-balances.md) - Understand aggregate balance effects. - [Balance transactions](https://studio.inttegro.com/machine/curl/products/balance-transactions.md) - Understand refund-linked money movement.