Orders

List, retrieve, and cancel orders. Anonymous orders carry a short-lived `bill_token` that the SDK persists for you, so guest order lookups Just Work after checkout.

client.orders.list() returns different results depending on how the client was constructed:

Guest client (getServerClient() with no accessToken, or the browser cimplify client with no signed-in shopper): returns nothing by default; the API has no customer to scope to. client.orders.get() still works on the same browser session that placed the order via the cached bill_token.
Authenticated client (getAuthenticatedServerClient() from the templates, or getServerClient({ accessToken }) from a custom integration): returns that customer's orders at this merchant.

See Sign in with Cimplify → Personalized server-side reads for the full setup.

Render orders for the signed-in shopper

app/account/orders/page.tsx

import { getAuthenticatedServerClient } from "@/lib/auth";

export const revalidate = 0; // personalized; do not ISR-cache

export default async function OrdersPage() {
  const client = await getAuthenticatedServerClient();
  const r = await client.orders.list({ limit: 20 });
  if (!r.ok) throw new Error(r.error.message);

  if (r.value.length === 0) {
    return <p>No orders yet.</p>;
  }
  return (
    <ul>
      {r.value.map((o) => (
        <li key={o.id}>#{o.order_number} · {o.status} · {o.total_price}</li>
      ))}
    </ul>
  );
}

If cimplify_access is missing (signed-out shopper), client.orders.list() returns the empty guest view. Branch on getSession() from lib/auth.ts if you want to redirect to sign-in instead.

List orders

const r = await client.orders.list({ limit: 20 })
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.length)
for (const order of r.value) {
  console.log(order.id, order.order_number, order.status)
}

Filter by status

const pending = await client.orders.list({ status: 'pending' })
const completed = await client.orders.list({ status: 'completed', limit: 50 })

// Convenience wrappers
const recent = await client.orders.getRecent(5)             // last 5
const cancelled = await client.orders.getByStatus('cancelled')

Get a single order

For guest orders the SDK appends the cached bill_token automatically; the lookup works in the same browser session that placed the order, with no auth.

import { parsePrice, formatPrice } from '@cimplify/sdk'

const r = await client.orders.get('ord_xxx')
if (!r.ok) return

const order = r.value
console.log(order.status)
console.log(order.items.length)
console.log(order.total_price)                       // Money string
console.log(formatPrice(parsePrice(order.total_price), order.currency))

Cancel an order

const cancelled = await client.orders.cancel('ord_xxx', 'changed_mind')
if (!cancelled.ok) {
  // Codes you'll see: ORDER_NOT_CANCELLABLE, ORDER_ALREADY_FULFILLED
  console.error(cancelled.error.code, cancelled.error.message)
}

// Idempotent retry: same key, same outcome on the server
await client.orders.cancel('ord_xxx', 'changed_mind', {
  idempotencyKey: 'cancel-ord_xxx-once',
})

Order status values

Status	Meaning
`pending`	Created, awaiting payment confirmation
`confirmed`	Accepted by the business
`preparing`	Being assembled or fulfilled
`ready`	Ready for pickup or delivery dispatch
`completed`	Fulfilled; terminal state
`cancelled`	Cancelled; terminal state
`refunded`	Payment refunded

Poll until terminal

async function pollUntilTerminal(orderId: string, intervalMs = 5000) {
  for (;;) {
    const r = await client.orders.get(orderId)
    if (!r.ok) return r

    const status = r.value.status
    if (status === 'completed' || status === 'cancelled' || status === 'refunded') {
      return r
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }
}

Method reference

Method	Returns
`list({ status?, limit?, offset? })`	`Result<Order[]>`
`get(orderId)`	`Result<Order>`
`cancel(orderId, reason?, opts?)`	`Result<Order>`
`getRecent(limit?)`	`Result<Order[]>`
`getByStatus(status)`	`Result<Order[]>`

Checkout Create the orders that this page lists
Subscriptions For recurring orders, see the subscription surface
Scheduling Reschedule or cancel a booking line item
Error handling Cancellation guards and retryable errors

Orders

On this page