Skip to main content
View as Markdown

Cancel an order

Orders that haven't reached Inttegro.OrderStatuses.Completed status can be canceled at any point in the lifecycle—whether the customer changed their mind before paying, an item went out of stock, or a suspected fraudulent transaction needs to be voided immediately. This guide shows you when cancellation is appropriate, how to trigger it, and what to expect from the order and payment objects afterward.

Use MCP before deciding to cancel

An authenticated AI agent can list or look up candidate orders and summarize the current state before your server calls the cancellation endpoint. Canceling an order itself still uses the Orders API.

MCP tools: list_orders, get_order or render_order_card

Prerequisites

When to cancel

Cancellation is the right action when the order should never complete. Common cases:

  • Customer request before payment — The customer abandoned the checkout or called in to withdraw. The order is in Inttegro.OrderStatuses.RequiresPayment and no money has moved yet.
  • Out-of-stock after order creation — You accepted the order but can't fulfill it. Cancel immediately to avoid the customer waiting on a payment that will never ship.
  • Duplicate or fraudulent order — Your fraud detection flagged the transaction before it completed. Cancel with reason "fraud" for your audit trail.
  • Timeout or expiry — You want to programmatically clean up stale orders that sat in Inttegro.OrderStatuses.RequiresPayment past your SLA.

What cancellation does not cover: If the order has already reached Inttegro.OrderStatuses.Completed status, you need a refund flow, not a cancellation. Cancellation is pre-completion only.

Cancel an order without refund

When the order has no captured payment—typically orders still in Inttegro.OrderStatuses.RequiresPayment before the customer confirms the OTP, or orders in Inttegro.OrderStatuses.Preparing that were never paid—cancel without triggering a refund. Set executeRefund to false or omit it entirely.

Cancel order

POST/orders/cancel
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.cancel({
  orderId: "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
  reason: "customer_request",
})

After a successful cancellation the order's status field becomes Inttegro.OrderStatuses.Canceled and the payment (if one exists) transitions to Inttegro.PaymentStatuses.Canceled as well. The canceledAt timestamp is set on the payment object for your audit trail.

Cancel an order and refund the customer

If the customer's mobile money payment was already charged before you cancel, pass executeRefund: true. Inttegro voids or reverses the payment in the same call—you don't need a separate refund API call.

Cancel with refund

POST/orders/cancel
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.cancel({
  orderId: "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
  reason: "inventory_unavailable",
  executeRefund: true,
})

Refund timing depends on the payment method. Mobile money reversals typically settle within minutes.

What happens after cancellation

Once canceled, an order cannot be reopened or modified. The cancellation is permanent. If the customer still wants to buy, create a new order.

The canceled order remains accessible via Lookup an order and Page through orders. It appears in your order history with status: Inttegro.OrderStatuses.Canceled indefinitely—useful for customer service, auditing, and financial reconciliation.

Your balance is not affected by a cancellation unless a payment was already captured and you set executeRefund: true. In that case, a negative balance transaction is created for the refund amount, reducing your available balance by the refunded sum.