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.

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