Skip to content
Docs
Get playground access

Order Management

Everything that happens to an order after the customer pays — capture, refund, cancel, amend, ship — and the three ways to do it, whether through the API, the Kustom Portal or a platform plugin.

BeforeCheckout →The customer paid. The amount is authorized, not captured.
  1. The order reaches your system
    Your push handler has created your own record of it.
    SEK 1 080,00 authorized
    POST
    /ordermanagement/v1/orders/{order_id}/acknowledge
    Tell Kustom the order is yours, which ends its retry schedule.
    Consider
    • Acknowledge only once you have stored your own record — retries stop here.
    • The order id is the same object the Checkout API returned.
    Read the guide →
  2. The warehouse packs the parcel
    The goods are on their way, so the money moves.
    SEK 1 080,00 captured
    POST
    /ordermanagement/v1/orders/{order_id}/captures
    Capture what you are shipping — in one call, or several as the order goes out.
    Consider
    • Capture as you ship. Part-shipments mean part-captures, and the status becomes PART_CAPTURED.
    • Nothing reaches your account until you capture.
    Read the guide →
  3. The customer returns the chinos
    They keep the shirts.
    SEK 700,00 refunded
    POST
    /ordermanagement/v1/orders/{order_id}/refunds
    Give back part of what you captured, without touching the rest of the order.
    Consider
    • The status stays CAPTURED and the refunded amount grows.
    • You can only refund what you have captured.
    Read the guide →
AfterFinance →Kustom pays out, and the settlement report reconciles against your orders.

Taking the payment is half the job. Order management is the other half: the operations you run on an order once the customer has paid — capturing the money, shipping the goods, refunding a return, cancelling what you can’t fulfill. It’s not optional. An authorized order that’s never captured is money you never receive, so every Kustom integration needs some route into these operations.

Why an order is not finished when it is paid

Section titled “Why an order is not finished when it is paid”

When a customer completes checkout, Kustom authorizes the amount — it reserves the money without moving it. Capture is what actually moves it to your bank account, and you capture when you fulfill. That gap between authorization and capture is where order management lives, and it’s why an order has both a remaining_authorized_amount and a captured_amount rather than a single balance.

The gap isn’t open forever. Authorizations expire — by default after about 28 days — and an expired authorization can’t be captured or extended. If your fulfillment routinely takes longer than that, that’s a conversation with Kustom about your account’s configured period, not something to solve per-order.

The three touchpoints

Section titled “The three touchpoints”

The same operations are available three ways. Which one fits is a question about volume and about what your storefront already runs on.

TouchpointFits whenTrade-off
Order Management APIYou handle many orders a day and want them managed from systems you already runYou write and maintain the integration
Kustom PortalYou handle a few orders a day by hand, or your platform can’t call external APIsManual, and it doesn’t synchronize with external systems
Platform pluginYour store runs on a supported platformYou get whatever the plugin exposes, and no more

These aren’t exclusive — the Portal stays available whatever else you use, which makes it the practical place to check what actually happened to an order while you’re building. One caveat worth knowing before you rely on it: if your integration is linked to an external system, the Portal’s manual order actions aren’t synchronized with it, so acting in both places can leave the two disagreeing.

What you can do to an order

Section titled “What you can do to an order”
  • Capture order. Capture the full amount, or capture partially as you ship in installments. Every capture can carry the order lines and the shipping details it covers.
  • Refund order. Refund a captured order in full or in part, and control which lines a partial refund is allocated against.
  • Cancel order. Cancel an order you haven’t captured and can’t fulfill, which releases the authorization.
  • Update order. Change the amount before capture, correct a shipping address, or attach your own references so the order is findable in your systems.
  • Extend order expiry. Extend the authorization when fulfillment will run past the default window.

Send a Kustom-Idempotency-Key on every write. Every POST and PATCH to Order Management moves money or changes the order. Send a Kustom-Idempotency-Key header with one UUID per operation, and reuse it when you retry, so a call repeated after a timeout runs once instead of twice. Idempotency and retries has the rules and the retry schedule.

Section titled “Related”

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.