Update or cancel an order

Everything on this page acts on an order that already exists, and most of it only works before the order is captured. Read first, change second: the order’s status and its amount fields decide which of these calls will be accepted. You need an order_id and a credential for the environment the order lives in.

Before you start

Paths are relative to your base URL: https://api.playground.kustom.co/ while testing, https://api.kustom.co/ in production.

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.

Read the order before changing it. Every failure below is really the same failure: the order wasn’t in a state that allows the change, and the order body is what tells you that.

Step by step

1. Read the order.

GET /ordermanagement/v1/orders/{order_id}

{
  "order_id": "7849fd84-47dc-4919-a7ce-xxxxxxxxxx",
  "status": "CAPTURED",
  "fraud_status": "ACCEPTED",
  "order_amount": 200,
  "original_order_amount": 200,
  "captured_amount": 200,
  "refunded_amount": 0,
  "remaining_authorized_amount": 0,
  "purchase_currency": "PLN"
}

Four amounts, and they’re the whole state machine. original_order_amount is what was authorized at checkout. order_amount is what it is now, after any amendment. captured_amount and refunded_amount are what has actually moved. remaining_authorized_amount is what you can still capture. When a call is refused, this is the object that explains why.

2. Change the amount, before capture. Lower the total when the customer drops a line, or when you can’t fulfill part of the order.

PATCH /ordermanagement/v1/orders/{order_id}/authorization
Kustom-Idempotency-Key: f06ebd62-6fc5-4021-a263-ef2c089974fa

{
  "order_amount": 6000,
  "description": "One line out of stock",
  "order_lines": [
    {
      "type": "physical",
      "reference": "123050",
      "name": "Tomatoes",
      "quantity": 10,
      "quantity_unit": "kg",
      "unit_price": 600,
      "tax_rate": 0,
      "total_amount": 6000,
      "total_tax_amount": 0
    }
  ]
}

Only possible while the order is uncaptured, uncancelled and unexpired.

3. Attach your own references, so the order is findable by your order number rather than only by Kustom’s id.

PATCH /ordermanagement/v1/orders/{order_id}/merchant-references
Kustom-Idempotency-Key: a01177d1-eb7d-4f37-a85b-b91da4bf8f31

{
  "merchant_reference1": "15632423",
  "merchant_reference2": "special order"
}

4. Correct the shipping address.

PATCH /ordermanagement/v1/orders/{order_id}/customer-details
Kustom-Idempotency-Key: c0b10c59-4d45-4b22-ab6c-0988762d5999

{
  "shipping_address": {
    "street_address": "123 Fake St",
    "postal_code": "12345",
    "city": "New York",
    "region": "NY",
    "country": "US"
  }
}

The billing address isn’t yours to change: the call takes only shipping_address, and the change can still be refused depending on the order’s state and its risk assessment.

5. Acknowledge a Checkout order. Tells Kustom you’ve taken responsibility for the order and created it in your own system. Do this when you handle the push callback.

POST /ordermanagement/v1/orders/{order_id}/acknowledge
Kustom-Idempotency-Key: 589d9d83-6abf-4f69-90f0-608765a84f58

6. Cancel what you can’t fulfill. Releases the authorization and returns the reserved money to the customer.

POST /ordermanagement/v1/orders/{order_id}/cancel
Kustom-Idempotency-Key: 60cceee2-7d9b-4837-9870-7734a8e767cd

Only an uncaptured order can be cancelled. Once any part is captured, the way back is a refund, not a cancellation.

After any change, re-read the order with step 1 and check the field you meant to change. For a cancel, status moves away from an authorized state. For an amount change, order_amount moves while original_order_amount stays where it was — which is exactly how you tell an amended order from a fresh one.

Troubleshooting

Every error carries an error_code, human-readable error_messages and a correlation_id. Act on the code, and quote the correlation id to support.

error_code	What it means
UPDATE_NOT_ALLOWED	The order’s state or risk assessment doesn’t allow changing its amount or address — read it and look at status
NOT_ALLOWED	The order isn’t in a state that permits this change — read it and look at status
NO_SUCH_ORDER	The order_id doesn’t exist, or belongs to the other environment
CANCEL_NOT_ALLOWED	The order has captures, so it can only be refunded

All four describe where the order is, not what you sent, so retrying an unchanged request fails identically. The error catalogue shows each one against the lifecycle, with the status the call needs.

Only ever branch on error_code. The error_messages array is English, aimed at a developer reading a log, and isn’t stable enough to parse or safe to show a customer.

Related

• Capture an order — take the money
• Refund an order — give it back
• Order Management — why these calls exist
• Order Management API reference — the generated specification