Payments

Orders

Create, update and cancel orders. An order holds the items, destination, currency and status of one cross-border purchase.

An order is the centre of every integration. It holds what the shopper is buying, where it's going, the currency they pay in, and the currency you settle in. Payments, refunds and landed-cost quotes all attach to an order.

This is preview documentation for a prototype. Endpoints, fields and keys are illustrative.

Create an order

curl https://api.international-orders.com/v1/orders \
  -u sk_test_51Hx...: \
  -H "Idempotency-Key: 6f1c2b9e-checkout-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 12900,
    "settlement_currency": "USD",
    "capture_method": "automatic",
    "shipping": { "country": "DE", "postal_code": "10115" },
    "items": [
      { "name": "Wool scarf", "hs_code": "6117.10", "quantity": 1, "unit_amount": 12900 }
    ],
    "metadata": { "cart_id": "1042" }
  }'

The response is the new order:

{
  "id": "ord_7Hc2kQ9xL4mP",
  "object": "order",
  "status": "requires_payment",
  "currency": "EUR",
  "amount": 12900,
  "settlement_currency": "USD",
  "client_secret": "ord_7Hc2kQ9xL4mP_secret_x8Yb...",
  "shipping": { "country": "DE", "postal_code": "10115" },
  "created": "2026-10-01T09:14:22Z"
}

Pass client_secret to Checkout Components in the browser. It lets the browser confirm this order and nothing else.

Key fields

Field	Required	Description
`currency`	Yes	The currency the shopper pays in
`amount`	Yes	Total in minor units, including shipping
`shipping.country`	Yes	Destination country, used for methods, duties and tax
`items`	Recommended	Line items. HS codes improve landed-cost accuracy
`settlement_currency`	No	The currency you're paid out in. Defaults to your account currency
`capture_method`	No	`automatic` (default) or `manual`. See capture
`metadata`	No	Up to 20 key-value pairs of your own data

Order status

An order moves through a small set of states. Listen for the matching webhooks rather than polling.

Status	Meaning
`requires_payment`	Created, waiting for the shopper to pay
`requires_action`	The shopper must complete a step, such as 3-D Secure
`authorized`	Funds are held but not captured (manual capture only)
`paid`	Payment captured. Safe to fulfil
`cancelled`	Cancelled before payment was captured
`refunded`	Fully refunded

Update an order

While an order is in requires_payment, you can change its amount, items or shipping address. This is useful when the shopper changes their basket or the delivery country.

curl https://api.international-orders.com/v1/orders/ord_7Hc2kQ9xL4mP \
  -u sk_test_51Hx...: \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15400, "shipping": { "country": "AT" } }'

Changing the country can change which payment methods are offered. Checkout Components refresh automatically.

Cancel an order

Cancel an order you no longer intend to collect. If a payment was authorised but not captured, the hold is released.

curl -X POST https://api.international-orders.com/v1/orders/ord_7Hc2kQ9xL4mP/cancel \
  -u sk_test_51Hx...:

You can't cancel a paid order. Issue a refund instead.