Orders

An order is the application-level record of a purchase: who bought what, for how much, against which payment instrument, and which transfer captured the funds. Orders are produced by checkout, embedded checkout, payment links, and subscription invoicing — there is no createOrder method.

Methods

`getOrder(orderId)`

GET /orders/:id.

`getOrders(params?)`

GET /orders. Standard pagination.

`updateOrderTags(orderId, tags)`

PATCH /orders/:id. The only mutable field is tags. Pass the full tag bag you want stored — server replaces, it does not merge.

await easy.updateOrderTags(orderId, {
  fulfilment_state: "shipped",
  tracking_number: "1Z999AA10123456784",
});

To list orders for a single customer, use getCustomerOrders.

Object shape

OrderData includes:

Field	Type	Notes
`id` / `order_number`	`string`	UUID + human-friendly number.
`subtotal_cents` / `tax_amount_cents` / `total_cents`	`number`	All in the smallest currency unit.
`currency`	`string`	ISO 4217.
`merchant_id` / `company_id`	`string`
`source`	`string`	`"checkout"`, `"payment_link"`, `"subscription"`, etc.
`payment_instrument`	`PaymentInstrumentData`	Instrument used.
`transfer`	`TransferData \| null`	The capture (null for declined / cancelled orders).
`payment_link_id`	`string \| null`	Set when sourced from a payment link.
`purchase_items`	`PurchaseItemData[]`	Line items with embedded `price_data` + `product_data`.
`buyer_details`	object	`email`, `phone`, name, billing address.
`shipping_address` / `billing_address`	`Address \| null`
`failure_code` / `failure_message`	`string \| null`	Populated on declines.
`tax_rate_id`	`string \| null`
`metadata` / `tags`	`Record<string, unknown>`

Examples

Reconcile recent orders

const orders = await easy.getOrders({ limit: 100 });
for (const o of orders.data) {
  if (!o.transfer || o.transfer.state !== "SUCCEEDED") continue;
  // post o.total_cents to your ledger keyed on o.order_number
}

Attach fulfilment metadata when a webhook fires

import { EasyWebhooks } from "@easylabs/node";

// Inside your webhook handler:
const event = EasyWebhooks.constructEvent(rawBody, sigHeader, secret);
if (event.type === "checkout.session.completed") {
  const order = event.data as { id: string; order_number: string };
  await easy.updateOrderTags(order.id, {
    fulfilment_state: "queued",
    queued_at: new Date().toISOString(),
  });
}

Surface a declined order to support

const { data: order } = await easy.getOrder(orderId);
if (order.failure_code) {
  console.warn(`Order ${order.order_number} failed: ${order.failure_message} (${order.failure_code})`);
}

Orders

On this page