انتقل إلى المحتوى الرئيسي

New: the Landed Cost API quotes duties and taxes at checkout in 40 markets. About the Landed Cost API

International OrdersInternational Orders

Reference

API overview

Base URL, conventions and every endpoint in the International Orders API, grouped by resource with links to each guide.

The International Orders API is organised around a few resources: orders, payments, refunds, payouts and landed-cost quotes. It uses predictable URLs, JSON request and response bodies, and standard HTTP status codes.

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

Base URL

https://api.international-orders.com/v1

The same URL serves test and live mode. The key you send decides which.

Conventions

  • Amounts are integers in the minor unit of the currency. 12900 in EUR is €129.00. Zero-decimal currencies such as JPY use the whole amount.
  • Currencies are three-letter ISO 4217 codes in upper case, such as EUR or USD.
  • Countries are two-letter ISO 3166-1 codes, such as DE or JP.
  • Timestamps are ISO 8601 strings in UTC, such as 2026-10-01T09:14:22Z.
  • IDs carry a prefix that tells you the object type: ord_, pay_, rf_, po_, lcq_, evt_.

Endpoints

Orders

MethodPathDescription
POST/v1/ordersCreate an order
GET/v1/orders/:idRetrieve an order
POST/v1/orders/:idUpdate an unpaid order
POST/v1/orders/:id/cancelCancel an order
GET/v1/ordersList orders

Guide: Orders

Payments

MethodPathDescription
POST/v1/orders/:id/captureCapture an authorised payment
GET/v1/payments/:idRetrieve a payment
GET/v1/paymentsList payments

Guide: Payments and capture

Refunds

MethodPathDescription
POST/v1/refundsRefund all or part of a payment
GET/v1/refunds/:idRetrieve a refund

Guide: Refunds

Payouts

MethodPathDescription
POST/v1/payoutsSend a payout
GET/v1/payouts/:idRetrieve a payout
GET/v1/payoutsList payouts

Guide: Payouts

Landed cost

MethodPathDescription
POST/v1/landed-cost/quotesQuote duties, taxes and fees
GET/v1/landed-cost/quotes/:idRetrieve a quote

Guide: Landed cost

Webhook endpoints

MethodPathDescription
POST/v1/webhook_endpointsRegister an endpoint
GET/v1/events/:idRetrieve an event

Guide: Webhooks

Pagination

List endpoints return up to 25 objects by default. Pass limit (1 to 100) and use starting_after with the last ID you received to fetch the next page.

curl "https://api.international-orders.com/v1/orders?limit=50&starting_after=ord_7Hc2kQ9xL4mP" \
  -u sk_test_51Hx...:

{
  "object": "list",
  "data": [{ "id": "ord_8Kd3mR0yM5nQ", "object": "order" }],
  "has_more": true
}

Idempotency

Send an Idempotency-Key header with every POST. If a request times out, retry it with the same key and you get the original result instead of a duplicate order or refund. Keys are kept for 24 hours.

Versioning

The API version is pinned to your account the first time you make a request. Pass an IO-Version header, such as 2026-09-01, to try a newer version on a single request before you upgrade.

Errors

Errors return a JSON body with a type, code and human-readable message. See Errors for the full list, or try requests in the playground.