Orders

List Orders

Requires customer authentication:

const orders = await client.orders.list({ page: 1, limit: 10 });
// { items: OrderListItem[], total, page, totalPages }

Order Detail

const order = await client.orders.get('ORD-2026-0042');

Cancel Order

Only PENDING orders can be cancelled:

const order = await client.orders.cancel('ORD-2026-0042');

Public Tracking

Track an order without logging in, using the tracking token from the confirmation email. For privacy this returns a minimized view (status, items, masked email, destination city), never the full address or phone, because the token travels in URLs and emails:

const { data, error } = await client.orders.track('a1b2c3d4-tracking-token');
// data: { orderNumber, status, paymentStatus, fulfillmentStatus, currency,
//         grandTotal, emailMasked, shippingCity, shippingCountry, items, createdAt }

Since SDK 2.8.0 the tracking view also carries everything an order page shows: the price summary (subtotal, shippingTotal, paymentFee, discountTotal, taxBreakdown), shippingMethodName, paymentMethodName, the chosen pickupPoint, and shipments with the carrier's trackingNumber and trackingUrl. Each item has imageUrl and productSlug for a link back to the product (null when the product was removed, so do not link). The order detail from get and the access-code flow carries the same fields.

Bank transfer details

For an unpaid order paid by bank transfer the order detail carries paymentInstructions (SDK 2.13.0): accountNumber, iban, bic, bankName, variableSymbol (digits only, at most 10, built from the method's pattern and the order number), amount, currency and the merchant's instructions. Render them on the confirmation page, otherwise the customer has nothing to pay with. It is null for other methods and once the order is paid. The order confirmation e-mail contains the same block.

const pay = order.paymentInstructions;
{pay && (
  <dl>
    <dt>Account</dt><dd>{pay.accountNumber ?? pay.iban}</dd>
    <dt>Variable symbol</dt><dd>{pay.variableSymbol}</dd>
    <dt>Amount</dt><dd>{formatPrice(pay.amount, pay.currency)}</dd>
  </dl>
)}

Verified Guest Access (email code)

To show a guest the full order detail (full address, items, totals) without an account, verify control of the order email with a one-time code. Knowing the order number alone is never enough. The request step always returns a generic success, so order numbers can't be enumerated.

// Step 1: send a 6-digit code to the email on the order (valid 10 minutes).
await client.orders.requestAccessCode('ORD-2026-0042', '[email protected]');

// Step 2: verify the code. On success you get the full detail plus a
// short-lived token (30 min) scoped to this single order.
const { data, error } = await client.orders.verifyAccessCode(
  'ORD-2026-0042',
  '[email protected]',
  '482913',
);
// data: { accessToken, expiresIn, order: <full OrderDetail> }

// Step 3 (optional): re-fetch the detail later using the token, no code needed.
const refetch = await client.orders.getByAccessToken(data.accessToken);

The code is single-use, expires in 10 minutes, and is burned after 5 wrong attempts. Every failure returns the same generic error, so nothing about the order can be probed.

Confirming Payment on Return

After paying, the customer is sent back to your thank-you page. Call syncPaymentOnReturn there, before you read the order: it makes the backend re-check the payment with the gateway right away.

// app/order/[orderNumber]/page.tsx (or wherever your returnUrl points)
await client.orders.syncPaymentOnReturn('ORD-2026-0042');

// Only now read the order, through a path that proves entitlement.
const { data } = await client.orders.track(trackingToken);

Why it matters: some gateways send no server-to-server notification at all (Tatrapay+ is one), so the customer's return is the fastest and sometimes the only way the payment gets confirmed quickly. For every other gateway it is a safety net for a notification that got lost on the way to us.

The call is safe to make unconditionally. It answers { ok: true } every time, including for an order number that does not exist, because order numbers are sequential and any other answer would let someone probe other people's orders. Read the real state afterwards with get, track or the guest access-code flow. If the call fails, ignore it and render the order as it stands: a backend poller keeps asking the gateway on its own schedule, so nothing is lost.

Order Statuses