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(array $query = []): array

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

An array with data (a list of Order), links and meta:

Errors

Example

$query = ['status' => 'processing', 'limit' => 50];

do {
    $page = $admin->orders->list($query);
    // … $page['data']
    $query['cursor'] = $page['meta']['nextCursor'];
} while ($query['cursor'] !== null);

Iterate over every order

$admin->orders->all(array $query = []): Generator

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

A generator of Order arrays, each:

Example

foreach ($admin->orders->all(['updatedSince' => $lastSyncedAt]) as $order) {
    $erp->saveOrder($order);
}

Get an order

$admin->orders->get(int $id): array

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(int $id, array $input, string|false|null $idempotencyKey = null): array

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

$order = $admin->orders->get(1042);

$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(int $id, array $input, string|false|null $idempotencyKey = null): array

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

$admin->orders->recordShipment(1042, [
    'carrier' => 'aramex',
    'trackingNumber' => '1234567890',
]);