Get order events

GET/order/{id}/events

Retrieve the event history for an order including status changes and tracking updates, oldest first. Pages by cursor (see Pagination): data stays a bare array, and meta carries has_more, next_cursor and the full event count (total). A request without cursor answers up to 500 events (1,000 with limit), which is nearly every order's whole history in one answer. To follow an order without a webhook address: keep meta.since from each answer and send it back as since with wait_seconds (at most 25). The answer comes as soon as the order has an event after since; when it has none yet, the request waits for one, up to wait_seconds, and then answers with an empty data and the same meta.since, so the next request asks from the same place. One request, counted once by the rate limit.

Credential: An API key in x-api-key
Scopes: orders:read

Parameters

idpath · stringrequired
The order's order_id, or its portal_order_id (ord_…): either resolves the same order. An id the order answered to before it was re-routed resolves too.
cursorquery · string
Opaque cursor: send back meta.next_cursor from the previous page for the page after it; omit it for the first page. Good only on this list, with a key of the same account and mode (test or live), and only for this order, and with the same filters (only limit may change); an altered or foreign cursor, or one sent with other filters, is refused with 400 validation_error. Wins over page when both are sent.
limitquery · integer
Events per page. Without cursor: 500 by default and 1000 at most, which is nearly every order's whole history in one answer — the size this list's page walk always had, so a first answer and page agree on it. With cursor: 20 by default and 100 at most, as on every list. Either way a value above the ceiling is clamped to it and one below 1 to 1, a fraction is truncated, and a missing, zero or non-numeric value takes the default; none is refused.
Default 500
pagequery · integerdeprecated
Deprecated: walk with cursor. The page number of the offset walk this operation always had, answered as before (offset, a row count, is accepted in its place), at the page size a request without cursor takes. Ignored when cursor or since is sent.
Default 1
sincequery · string
The position to read on from: meta.since from an earlier answer for this order (a meta.next_cursor is accepted too), sent back unchanged. Only events after it are returned, oldest first, at a cursor page's size (limit 20 by default, 100 at most). Good only for this order, with a key of the same account and mode; an altered or foreign value is refused with 400 validation_error and details.parameter: "since", and so is a request that sends cursor as well. Omit it to read from the first event.
wait_secondsquery · integer
How long to wait for an event when there is none to return yet (a long poll). 0, the default, answers at once. Otherwise the request answers as soon as an event is found — the order's events are re-read every 2 seconds — or after this many seconds with an empty data. A value above 25 is clamped to 25, a fraction is truncated, and a missing, negative or non-numeric value is 0; none is refused.
Default 0

Request

Try it

GET /api/v1/order/{id}/events

curl "https://portal.printedsimply.com/api/v1/order/test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk/events" \
  -H "x-api-key: ps_test_YOUR_KEY"

Response `200`

The order's history, oldest first. data is a BARE ARRAY — the count, has_more and next_cursor live in meta, because there is nowhere in the body to hang them without breaking every existing client.

data is a list; each entry:

actionstringrequired
detailsstring | nullrequired
timestampstring (date-time)required

meta

pageintegerdeprecated
The page number of the deprecated offset walk, on the lists that published it (orders and an order's events, on every request without cursor; products, on a request that sent page). Absent on a cursor walk, where no page number would be true.
totalinteger
Every row matching the request's filters, on the lists that count them (orders, an order's events, assets and products).
limitinteger
The page size applied, which is not necessarily the one asked for: a larger limit is clamped. Absent only on a GET /products request without cursor that sent no limit, which answers every match.
pagesintegerdeprecated
total over limit, rounded up, beside page (orders and an order's events). Absent on a cursor walk.
next_cursorstring | nullrequired
Send it back as cursor for the next page; null exactly when has_more is false. Opaque: pass it back unchanged. Good only on the list that returned it, with a key of the same account and mode (test or live), and with the same filters.
has_morebooleanrequired
Whether another page follows this one. Decided from one row past this page, never from a page that came back short — so a page after has_more: true can come back empty only if rows were deleted in between, and the walk still ends at the first has_more: false.
sincestring | null
On GET /order/{id}/events only: where to ask from next — the position of the last event in this answer, or, when it has none, the position the request read from. Send it back as since (with wait_seconds to wait for the next event). Unlike next_cursor it is not null at the end of the history; it is null only when the order has no events and the request named no position. Opaque, and bound like a cursor to this order, account and key mode.

Example response

{
  "status": "success",
  "data": [
    {
      "action": "order_submitted",
      "details": "A test order: nothing is charged, printed or sent. The total is what a live order would pay.",
      "timestamp": "2026-10-15T15:00:10.000Z"
    },
    {
      "action": "artwork_checked",
      "details": "The artwork prints well (1200×1200 px, 400 DPI at 3×3 in).",
      "timestamp": "2026-10-15T15:00:10.000Z"
    }
  ],
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a",
  "meta": {
    "page": 1,
    "pages": 1,
    "limit": 500,
    "total": 2,
    "has_more": false,
    "next_cursor": null,
    "since": "eyJyIjoib3JkZXJfZXZlbnRzIiwiayI6WyIyMDI2LTEwLTE1VDE1OjAwOjEwLjAwMFoiLCJjdnEwNHlsNjQ5bzd0M283YWJpa3Y5NzE0Il19.9452219bf0c9044af2bbb15342e6bd3d"
  }
}

Errors

400validation_error
Invalid request body or parameters. When the request failed the operation's schema, details carries formErrors (problems with the request as a whole), fieldErrors (messages keyed by top-level field) and errors: one { pointer, code, message } per refused value, pointer an RFC 6901 JSON pointer into the body (or into the object of query parameters, for a query parameter) — /items/0/sku, with ~ written ~0 and / written ~1, and "" for the request as a whole. POST /v1/orders/bulk answers errors as one { index, details } per refused order, each details with its own pointers from the request body (/orders/3/items/0/sku); POST /v1/orders/multi-ship keeps errors as the { formErrors, fieldErrors } it always published; POST /v1/mockups/generate and POST /v1/products/recommend keep their fields at the top of details, with errors beside them. A refusal of a rule the schema cannot state (an asset that does not exist, an expiry too soon) names it in message and carries no errors.
401invalid_api_key missing_api_key key_expired
Missing, invalid or expired API key: missing_api_key (none sent), invalid_api_key (unknown or revoked), key_expired (past the expiry set when it was created; create a new key).
404
Resource not found
429rate_limit_exceeded daily_quota_exceeded
Rate limit exceeded. Two windows can produce this status and error.code says which: rate_limit_exceeded for the per-minute sliding window, daily_quota_exceeded for the plan's daily quota. Both carry Retry-After; the daily one also carries X-Daily-Limit and X-Daily-Remaining. The per-minute limits are plan-based — see Rate Limits above, or call GET /v1/me for this credential's own figures.

Every Orders operation

Parameters

idpath · stringrequired

The order's order_id, or its portal_order_id (ord_…): either resolves the same order. An id the order answered to before it was re-routed resolves too.

cursorquery · string

Opaque cursor: send back meta.next_cursor from the previous page for the page after it; omit it for the first page. Good only on this list, with a key of the same account and mode (test or live), and only for this order, and with the same filters (only limit may change); an altered or foreign cursor, or one sent with other filters, is refused with 400 validation_error. Wins over page when both are sent.

limitquery · integer

Events per page. Without cursor: 500 by default and 1000 at most, which is nearly every order's whole history in one answer — the size this list's page walk always had, so a first answer and page agree on it. With cursor: 20 by default and 100 at most, as on every list. Either way a value above the ceiling is clamped to it and one below 1 to 1, a fraction is truncated, and a missing, zero or non-numeric value takes the default; none is refused.

Default 500

pagequery · integerdeprecated

Deprecated: walk with cursor. The page number of the offset walk this operation always had, answered as before (offset, a row count, is accepted in its place), at the page size a request without cursor takes. Ignored when cursor or since is sent.

Default 1

sincequery · string

The position to read on from: meta.since from an earlier answer for this order (a meta.next_cursor is accepted too), sent back unchanged. Only events after it are returned, oldest first, at a cursor page's size (limit 20 by default, 100 at most). Good only for this order, with a key of the same account and mode; an altered or foreign value is refused with 400 validation_error and details.parameter: "since", and so is a request that sends cursor as well. Omit it to read from the first event.

wait_secondsquery · integer

How long to wait for an event when there is none to return yet (a long poll). 0, the default, answers at once. Otherwise the request answers as soon as an event is found — the order's events are re-read every 2 seconds — or after this many seconds with an empty data. A value above 25 is clamped to 25, a fraction is truncated, and a missing, negative or non-numeric value is 0; none is refused.

Default 0

Response 200

data is a list; each entry:

actionstringrequired
detailsstring | nullrequired
timestampstring (date-time)required

meta

pageintegerdeprecated
The page number of the deprecated offset walk, on the lists that published it (orders and an order's events, on every request without cursor; products, on a request that sent page). Absent on a cursor walk, where no page number would be true.
totalinteger
Every row matching the request's filters, on the lists that count them (orders, an order's events, assets and products).
limitinteger
The page size applied, which is not necessarily the one asked for: a larger limit is clamped. Absent only on a GET /products request without cursor that sent no limit, which answers every match.
pagesintegerdeprecated
total over limit, rounded up, beside page (orders and an order's events). Absent on a cursor walk.
next_cursorstring | nullrequired
Send it back as cursor for the next page; null exactly when has_more is false. Opaque: pass it back unchanged. Good only on the list that returned it, with a key of the same account and mode (test or live), and with the same filters.
has_morebooleanrequired
Whether another page follows this one. Decided from one row past this page, never from a page that came back short — so a page after has_more: true can come back empty only if rows were deleted in between, and the walk still ends at the first has_more: false.
sincestring | null
On GET /order/{id}/events only: where to ask from next — the position of the last event in this answer, or, when it has none, the position the request read from. Send it back as since (with wait_seconds to wait for the next event). Unlike next_cursor it is not null at the end of the history; it is null only when the order has no events and the request named no position. Opaque, and bound like a cursor to this order, account and key mode.

Example response

{
  "status": "success",
  "data": [
    {
      "action": "order_submitted",
      "details": "A test order: nothing is charged, printed or sent. The total is what a live order would pay.",
      "timestamp": "2026-10-15T15:00:10.000Z"
    },
    {
      "action": "artwork_checked",
      "details": "The artwork prints well (1200×1200 px, 400 DPI at 3×3 in).",
      "timestamp": "2026-10-15T15:00:10.000Z"
    }
  ],
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a",
  "meta": {
    "page": 1,
    "pages": 1,
    "limit": 500,
    "total": 2,
    "has_more": false,
    "next_cursor": null,
    "since": "eyJyIjoib3JkZXJfZXZlbnRzIiwiayI6WyIyMDI2LTEwLTE1VDE1OjAwOjEwLjAwMFoiLCJjdnEwNHlsNjQ5bzd0M283YWJpa3Y5NzE0Il19.9452219bf0c9044af2bbb15342e6bd3d"
  }
}

Errors

400validation_error

Invalid request body or parameters. When the request failed the operation's schema, details carries formErrors (problems with the request as a whole), fieldErrors (messages keyed by top-level field) and errors: one { pointer, code, message } per refused value, pointer an RFC 6901 JSON pointer into the body (or into the object of query parameters, for a query parameter) — /items/0/sku, with ~ written ~0 and / written ~1, and "" for the request as a whole. POST /v1/orders/bulk answers errors as one { index, details } per refused order, each details with its own pointers from the request body (/orders/3/items/0/sku); POST /v1/orders/multi-ship keeps errors as the { formErrors, fieldErrors } it always published; POST /v1/mockups/generate and POST /v1/products/recommend keep their fields at the top of details, with errors beside them. A refusal of a rule the schema cannot state (an asset that does not exist, an expiry too soon) names it in message and carries no errors.

401invalid_api_key missing_api_key key_expired

Missing, invalid or expired API key: missing_api_key (none sent), invalid_api_key (unknown or revoked), key_expired (past the expiry set when it was created; create a new key).

404

Resource not found

429rate_limit_exceeded daily_quota_exceeded

Rate limit exceeded. Two windows can produce this status and error.code says which: rate_limit_exceeded for the per-minute sliding window, daily_quota_exceeded for the plan's daily quota. Both carry Retry-After; the daily one also carries X-Daily-Limit and X-Daily-Remaining. The per-minute limits are plan-based — see Rate Limits above, or call GET /v1/me for this credential's own figures.

Get order events

Parameters

Request

Response 200

Errors

Get order events

Parameters

Request

Response 200

Errors

Response `200`

Response `200`