# 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.

Paid is not finished. Kustom reserves the money at checkout and nothing reaches your account until you capture it — so this is where an order becomes revenue.

**Before:** [Checkout](/checkout/how-it-works/) — 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.
   Outcome: SEK 1 080,00 authorized
   - POST `/ordermanagement/v1/orders/{order_id}/acknowledge` (you call Kustom) — Tell Kustom the order is yours, which ends its retry schedule.
     - 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](/order-management/update-and-cancel/)
2. **The warehouse packs the parcel**
   The goods are on their way, so the money moves.
   Outcome: SEK 1 080,00 captured
   - POST `/ordermanagement/v1/orders/{order_id}/captures` (you call Kustom) — Capture what you are shipping — in one call, or several as the order goes out.
     - 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](/order-management/capture/)
3. **The customer returns the chinos**
   They keep the shirts.
   Outcome: SEK 700,00 refunded
   - POST `/ordermanagement/v1/orders/{order_id}/refunds` (you call Kustom) — Give back part of what you captured, without touching the rest of the order.
     - The status stays CAPTURED and the refunded amount grows.
     - You can only refund what you have captured.
   - [Read the guide](/order-management/refunds/)
**After:** [Finance](/finance/) — 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

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

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

| Touchpoint | Fits when | Trade-off |
|---|---|---|
| **Order Management API** | You handle many orders a day and want them managed from systems you already run | You write and maintain the integration |
| **Kustom Portal** | You handle a few orders a day by hand, or your platform can't call external APIs | Manual, and it doesn't synchronize with external systems |
| **Platform plugin** | Your store runs on a supported platform | You 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

- **[Capture order](/order-management/capture/).** 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](/order-management/refunds/).** Refund a captured order in full or in part,
  and control which lines a partial refund is allocated against.
- **[Cancel order](/order-management/update-and-cancel/).** Cancel an order you haven't captured
  and can't fulfill, which releases the authorization.
- **[Update order](/order-management/update-and-cancel/).** 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](/order-management/extend-authorization/).** 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](/order-management/idempotency-and-retries/) has the rules and the retry schedule.

## Related

- [Capture an order](/order-management/capture/) — the call that moves the money
- [Update or cancel an order](/order-management/update-and-cancel/) — read, amend, cancel, acknowledge
- [Extend order expiry](/order-management/extend-authorization/) — when fulfillment runs long
- [Authentication and environments](/api/authentication/) — the credential these calls use