Order

Source: api.ts:159

A placed order, exactly as the orders API returns it — its lines, totals, shipping, addresses, and the URLs the shopper is sent to next.

This is the order object the SDK holds: creating an order, fetching one by ref_id, and adding a post-purchase upsell all resolve to it, and it is what the order store (useOrderStore) keeps on a receipt or upsell page. Read it when you need any total, line, or address.

OrderData is a smaller, older view of this same object — six fields plus loosely typed lines/user — and is only the declared payload type of the order:completed event. At runtime that event delivers a full Order.

Every money field is a decimal string in the order's currency ("59.98"), not a number, so it survives JSON without rounding. Parse it before doing arithmetic.

Example

import { useOrderStore, type Order } from '@next-commerce/campaign-cart';

const order: Order | null = useOrderStore.getState().order;
if (order) {
  console.log(order.number, order.total_incl_tax); // "NX-10428" "59.98"
  const upsells = order.lines.filter(line => line.is_upsell);
  console.log(`${upsells.length} upsell line(s) added after checkout`);
}

Properties

ref_id: string

The order's reference. It is the id everything else keys off: the SDK reads it from ?ref_id= to load the order on a receipt or upsell page, and sends it back to add post-purchase upsells.

number: string

Human-facing order number to show the customer, e.g. "NX-10428".

currency: string

ISO currency code the order was charged in, e.g. "USD".

lines: OrderLine[]

Every line on the order, one per package. Lines added after checkout by an upsell carry is_upsell: true, which is how a thank-you page tells the original purchase apart from what was added later.

total_excl_tax: string

Order grand total before tax.

total_incl_tax: string

Order grand total the customer was charged, tax included.

total_tax: string

Tax charged on the order.

total_discounts: string

Everything discounted off the order — offer discounts and vouchers together.

shipping_excl_tax: string

Shipping charged before tax.

shipping_incl_tax: string

Shipping charged, tax included.

shipping_tax: string

Tax charged on shipping.

shipping_method: string

Display name of the shipping method chosen at checkout, e.g. "Standard".

shipping_code: string

Code of that shipping method, matching the campaign's shipping_methods[].code.

display_taxes: string

Tax presentation hint the orders endpoint returns for stores that show tax as a separate line. The SDK does not read it; it is here because the API sends it. Absent for stores that do not display tax separately.

discounts: Discount[]

The discounts applied to the order, itemised. Each entry carries amount plus, when the API knows them, offer_id, name, description, and percentage. Use total_discounts for the single "you saved" figure.

user: OrderUser

The customer the order was placed for — name, email, and phone.

shipping_address: OrderAddress

Where the goods ship. Absent on orders with nothing to ship.

billing_address: OrderAddress

Where the card is billed. Absent when it is the same as the shipping address.

attribution: MarketingAttribution

The marketing attribution captured with the order — UTM parameters, click ids, affiliate and funnel. Absent when the visit carried none.

payment_method: PaymentMethod | null

How the order was paid for, as the API's own code — "paypal", "card_token", "apple_pay" and so on. The orders API records the method chosen at checkout and returns it on every order it sends back, so a receipt page can name it.

null on an order the platform has no method recorded for. There is no "assume card" default: a page that shows this shows nothing when it is null, rather than naming a method the shopper did not use.

data-next-display="order.paymentMethod" renders this through a friendlier label for the common methods — see the order-display guide's display paths.

Two of PaymentMethod's values only ever arrive here and can never be sent: external, a payment taken outside the platform, and saved_card, a card already on file. Both are recorded in the admin dashboard.

order_status_url: string

URL of the hosted order-status/receipt page for this order.

payment_complete_url: string

Where to send the shopper to finish paying, for payment methods that need a further step (PayPal, Klarna, and other redirect flows). When present the SDK redirects here instead of to order_status_url.

supports_post_purchase_upsells: boolean

Whether lines may still be added to this order. false means the order is closed to upsells, and the SDK hides every offer on an upsell page rather than letting a shopper accept one that will fail.

is_test: boolean

true for a test-mode order — a real order record, but no money moved.

statement_descriptor: string | null

What shows up next to the charge on the customer's card or bank statement. Up to 20 characters — letters, numbers, spaces, and ., -, *.

null or absent when the store has not configured one; the gateway's own default descriptor applies instead. The SDK does not read this field today — declared because the orders API sends it on every order.