Orders

The shop's orders, with their lines, totals, addresses and shipment: read them, move them through their statuses, and record the shipments your own system books.

Reach them through admin.orders. Reading needs the orders:read scope, changing them orders:write.

List orders

admin.orders.list(query?: ListQuery & { status?: string; paymentStatus?: string; source?: string }): Promise<CursorPage<Order>>

One page of the shop's orders, by status, payment status or source; or oldest change first with updatedSince. Read the next page with meta.nextCursor as cursor. Scope: orders:read.

Parameters

Query fields

Returns

A CursorPage<Order>:

Errors

Example

const query = { status: 'processing', limit: 50 };
let cursor: string | null = null;

do {
    const page = await admin.orders.list(cursor ? { ...query, cursor } : query);
    // … page.data
    cursor = page.meta.nextCursor;
} while (cursor !== null);

Iterate over every order

admin.orders.all(query?: ListQuery & { status?: string; paymentStatus?: string; source?: string }): AsyncGenerator<Order, void, undefined>

Every order matching the query, one at a time, fetching the next page as you read. It takes the same query as list, without cursor. Scope: orders:read.

Returns

An async generator of Order, each:

Example

for await (const order of admin.orders.all({ updatedSince: lastSyncedAt })) {
    await erp.saveOrder(order);
}

Get an order

admin.orders.get(id: number): Promise<Order>

One order by its id, with its lines, totals, addresses and shipment. Scope: orders:read.

Parameters

Returns

An Order:

Errors

Change an order's status

admin.orders.updateStatus(id: number, input: OrderStatusInput, options?: RequestOptions): Promise<Order>

Moves the order to a status. Nothing goes back to unconfirmed; a move the order's status doesn't allow is 422 invalid_transition. With notifyCustomer, a cancelled order's customer is emailed. Send the updatedAt you read in input so a newer order is refused with 409 edit_conflict. Scope: orders:write.

Parameters

Request fields

Returns

The changed Order:

Errors

Example

const order = await admin.orders.get(1042);

await admin.orders.updateStatus(1042, {
    status: 'processing',
    note: 'Picked in the warehouse',
    notifyCustomer: false,
    updatedAt: order.updatedAt, // 409 edit_conflict if it changed
});

Record a shipment

admin.orders.recordShipment(id: number, input: OrderShipmentInput, options?: RequestOptions): Promise<Order>

Records the carrier and tracking number your own system booked, once, while the order is ready to ship or shipped (409 shipment_not_allowed otherwise). carrierName is required when carrier is other. Scope: orders:write.

Parameters

Request fields

Returns

The changed Order:

Errors

Example

await admin.orders.recordShipment(1042, {
    carrier: 'aramex',
    trackingNumber: '1234567890',
});