List orders

GET/orders

Retrieve a paginated list of your orders, newest first, with optional filters. Pages by cursor (see Pagination): send back meta.next_cursor as cursor until meta.has_more is false, a keyset walk that cannot repeat or skip a row while orders are being written. Reconciliation should use the cursor. The deprecated page walk is still answered as before.

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

Parameters

statusquery · string
Filter by order status. An unknown value is refused with 400 validation_error, never ignored — an unrecognised status would otherwise match no row and answer 200 with an empty page, which is indistinguishable from having no such orders. Current statuses: pending_approval, pending_payment, paid, accepted, in_production, quality_check, shipped, delivered, cancelled, issue_flagged, rerouting. Historical values, accepted so orders older than this vocabulary stay reconcilable but no longer written: pending, processing, on-hold, completed, refunded, failed.
One of pending_approval pending_payment paid accepted in_production quality_check shipped delivered cancelled issue_flagged rerouting pending processing on-hold completed refunded failed
referencequery · string
Exact match on the reference you supplied at create. Use it to reconcile your own order ids against ours — including after a create response you never received.
fromquery · string (date-time)
Filter orders created on or after this date. A value that is not a date, or a from later than to, returns 400 validation_error — it is never dropped, because an unfiltered page is indistinguishable from a windowed one.
toquery · string (date-time)
Filter orders created on or before this date. A value that is not a date returns 400 validation_error.
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 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
Orders per page: 20 by default, 100 at most. A value above 100 is clamped to 100 and one below 1 to 1, a fraction is truncated, and a missing, zero or non-numeric value falls back to 20; none is refused.
Default 20
pagequery · integerdeprecated
Deprecated: walk with cursor. The page number of the offset walk this operation always had, answered as before (limit 20 by default, 100 at most; offset, a row count, is accepted in its place). An order written while you page shifts every offset behind it; a cursor cannot be shifted. Ignored when cursor is sent, and a cursor walk's meta carries no page or pages.
Default 1

Request

Try it

GET /api/v1/orders

curl "https://portal.printedsimply.com/api/v1/orders" \
  -H "x-api-key: ps_test_YOUR_KEY"

Response `200`

Paginated list of orders. meta carries has_more, next_cursor (null on the last page), total and limit — plus page and pages except on a cursor walk. Each row carries the reference you supplied at create (null if you supplied none) and the guarantee in force on that order (null when it carries none).

data is a list; each entry:

order_idstringrequired
The fulfilment network's order id — the one GET /v1/order/{id} and every other order operation take.
portal_order_idstringrequired
This platform's own id for the order.
providerstringrequired
The fulfilment lane that holds the order.
made_byobject | nullrequired
The independent network shop that produced an order, or null when an in-house lane did. GET /v1/orders and GET /v1/order/{id} build it from the same helper and both $ref this, so they cannot describe one fact two ways — which they did, one of them calling it a string. Every order placed on this portal is made at our own plant, so it is null on them; a shop is named only on an order placed before that.
made_by.namestringrequired
The shop's display name.
made_by.slugstringrequired
The shop's directory slug.
made_by.profile_urlstring (uri)required
Its public profile page on this platform.
guaranteeobject | nullrequired
The delivery guarantee in force on this order, or null when the order carries none (guarantees are issued only on lanes whose measured on-time record clears the floor, and only while the feature is enabled). The keys mirror the guarantee block returned by POST /orders/quote, so this is the object you were quoted, read back, plus what has since happened to it.
guarantee.guarantee_idstringrequired
Same id the quote issued.
guarantee.deliver_bystring (date-time)required
The date this order is guaranteed to arrive by.
guarantee.quality_standardstringrequired
The quality standard guaranteed ("standard" in v1).
guarantee.confidencenumberrequired
Lower bound on the lane's on-time probability at issue time (Wilson), between 0 and 1.
guarantee.remedyobjectrequired
The promise. cap_cents is the ceiling on what a breach can pay — never an amount owed or paid; read remedies for what was actually recorded.
guarantee.remedy.typestringrequired
credit is the only remedy issued today, and the one that settles as a real refund. remake and expedite are reserved for the ops-driven remedies; one would settle as not_applicable rather than pay.
One of credit remake expedite
guarantee.remedy.cap_centsintegerrequired
guarantee.statusstringrequired
issued while the promise is open, honored once the order was delivered on time, remedied once it was not. There is deliberately no breached value: a breach and its capped remedy are recorded in one transaction (so two overlapping sweeps cannot both pay out), so the terminal state of a broken promise is remedied and whether the money moved is the remedy's own status.
One of issued honored remedied
guarantee.issued_atstring (date-time)required
guarantee.resolved_atstring (date-time) | nullrequired
When the guarantee was honored or remedied; null while still open.
guarantee.remediesobject[]required
Remedies recorded against this guarantee. Empty unless it was breached.
guarantee.remedies[].typestringrequired
One of credit remake expedite
guarantee.remedies[].amount_centsintegerrequired
What was recorded, capped at the order value at issue.
guarantee.remedies[].statusstringrequired
applied is the only value that means money moved — a real refund on the order's charge. not_applicable is the ordinary sandbox outcome (a test order has no charge) and also covers a remake/expedite, which is an ops action rather than an automatic payment. failed is an owed remedy that has not been paid, kept distinct from not_applicable so it stays visible.
One of pending applied failed not_applicable
guarantee.remedies[].applied_atstring (date-time) | nullrequired
guarantee.remedies[].created_atstring (date-time)required
referencestring | nullrequired
The reference you supplied at creation, echoed back. Null on orders placed without one, and on every order that predates the column.
vatstring | nullrequired
The tax-registration number declared on this order; null when none was supplied.
landed_costobject | nullrequired
What the border cost on this order, as recorded for the parcel that ships. Null on a domestic shipment — there is no border, so there is nothing to state, and a row of zeros would read like a customs assessment that came to nothing. When a cross-border order has no stored figures, recorded is false and only destination_country and not_recorded_reason are present: the duty, tax and FX rates that applied on the day are not recoverable, and backfilling them with today's rates would be a fabricated record rather than a missing one. That is what an order placed before these figures were stored looks like, and also a free replacement order, which carries no charged goods value to assess. The figures are a snapshot, never recomputed on read, so a stale figure cannot be mistaken for a current one — but they ARE re-recorded when the parcel itself changes, because the border is costed against the destination, the goods and the shipping charge. Change the address, add or cancel a line, change a quantity or change the shipping method and the order is costed again at that moment; recorded_at moves with it, and it is the order's creation time until something does. An order re-routed to a domestic address goes back to null. estimated stays true throughout: on DAP the courier bills the recipient directly, so we never learn what customs actually assessed.
landed_cost.recordedbooleanrequired
False when no landed cost was stored for this order.
landed_cost.destination_countrystring
ISO 3166-1 alpha-2.
landed_cost.not_recorded_reasonstring
Present only when recorded is false.
landed_cost.recorded_atstring (date-time)
When the figures were computed — never the moment of the read. The order's creation time, or the moment of the last change to its destination, lines or shipping charge.
landed_cost.duty_basisstring
DAP today: goods and shipping are collected at checkout, and the courier bills the recipient for duties and import tax on delivery.
One of DDP DAP
landed_cost.duty_ratenumber
landed_cost.tax_ratenumber
landed_cost.breakdownobject
landed_cost.breakdown.goods_centsinteger
landed_cost.breakdown.shipping_centsinteger
landed_cost.breakdown.duties_centsinteger
landed_cost.breakdown.tax_centsinteger
landed_cost.total_landed_centsinteger
What the buyer ends up paying in total.
landed_cost.pre_collected_centsinteger
Collected at checkout. Equals goods + shipping — never more than was charged.
landed_cost.due_on_delivery_centsinteger
Billed by the courier on delivery. Sums with pre_collected_cents to the total.
landed_cost.presentmentobject
landed_cost.presentment.currencystring
landed_cost.presentment.amount_centsinteger
landed_cost.presentment.minor_unitsinteger
landed_cost.presentment.fx_ratenumber
landed_cost.estimatedboolean
landed_cost.notestring
statusstringrequired
The order's lifecycle status, from the same vocabulary the status filter above accepts.
One of pending_approval pending_payment paid accepted in_production quality_check shipped delivered cancelled issue_flagged rerouting pending processing on-hold completed refunded failed
issue_reasonstring | nullrequired
Why the order is issue_flagged, as GET /v1/order/{id} reports it; null when it is not flagged, or no reason fits.
One of artwork_unprintable address_undeliverable shipment_exception on_hold cancellation_pending
totalstringrequired
What the order was charged, formatted for display — a dollar string such as $42.00, NOT an integer of cents. total_cents beside it carries the same money as an integer, under the name GET /v1/order/{id} uses; read that one. Kept because the shape is published and changing it would break every caller reading it.
shippingstringrequired
The shipping charge, formatted the same way as total; shipping_cents is the same money in cents.
total_centsintegerrequired
What the order was charged, in cents — the same money as total, and the same field GET /v1/order/{id} carries.
shipping_centsintegerrequired
The shipping charge, in cents — the same money as shipping.
is_testbooleanrequired
True on a sandbox order. The same value as test_mode beside it; kept because it is published.
test_modebooleanrequired
True on a sandbox order, false on a live one — is_test under the name the create response and GET /v1/order/{id} use. Present on every row here (the order read omits it on a live order).
channelstringrequired
The surface that placed the order. On hosted, acp and ucp a shopper paid your store, and total is that sale; on every other channel you placed the order and total is what it cost you. unknown is an order older than the record.
One of acp ucp mcp verified_agent oauth_app api dashboard autopilot hosted storefront unknown
drop_idstring | nullrequired
The drop a shopper bought this order on; null on an order no drop sold.
itemsobject[]required
The order's lines. Each carries the id our item and return operations resolve — see OrderLine.
items[].idstringrequired
This line's id. Use it as {itemId} on PUT /v1/{id}/item/{itemId} and DELETE /v1/{id}/item/{itemId}/cancel.
items[].skustringrequired
items[].quantityintegerrequired
at least 1
items[].unit_price_centsintegerrequired
items[].artworkobject
The line's artwork declaration, as the order accepted it: how the artwork was made, and who approved it and when. Absent on a line that declared none.
items[].artwork.provenancestring
How the artwork was made: human (made by a person), ai_assisted (a person made it with a model's help) or ai_generated (a model made it).
One of human ai_assisted ai_generated
items[].artwork.approved_bystring
Who approved the artwork for print: a name or an email address, at most 200 characters. Control and invisible formatting characters are removed and whitespace collapsed before it is stored. Send it with approved_at.
non-empty · at most 200 characters
items[].artwork.approved_atstring (date-time)
When the artwork was approved: an ISO 8601 date-time with a time zone, not in the future. Stored and echoed in UTC. Send it with approved_by.
line_itemsobject[]required
The same lines as items, under the name GET /v1/order/{id} publishes them as, so one name reads the lines from either.
The same fields as items
actionsobjectrequired
Which changes this order still takes, read from the same checks the operations refuse on, so a client can show or offer an action without trying it first. true means the order's own state does not refuse it; the request is still checked as usual (the key's scope; the line an item action names, which must exist and, on a live order at our own plant, carry its artwork; and on a live order the facility, which can refuse a change with 502 fulfillment_error). false names the refusal the operation would give. Live PrintedSimply orders have add_item, update_item and upgrade_shipping false; only supported no-cost or downward shipping requests remain requestable. On other orders a shopper paid for (a drop, a checkout link or an agent checkout), update_item and update_shipping stay true because a decrease or a downgrade is allowed, while an increase or an upgrade is refused 409 shopper_paid_order, as add_item is.
actions.cancelbooleanrequired
DELETE /order/{id}/cancel. True only before production (pending_payment, paid or accepted); false once the order is cancelled (400 already_cancelled) or past that (409 not_cancellable).
actions.update_addressbooleanrequired
PUT /order/{id}/address. False on an order an independent shop made (501 not_supported_by_provider) and once the order is past the point of change (409 order_not_modifiable).
actions.update_shippingbooleanrequired
PUT /order/{id}/shipping. False for the reasons update_address is.
actions.upgrade_shippingbooleanrequired
Positive-cost PUT /order/{id}/shipping upgrades. False for live PrintedSimply orders (501 not_supported_by_provider), shopper-paid orders (409 shopper_paid_order), and when update_shipping is false. A downgrade or unchanged method can still be allowed when this is false.
actions.add_itembooleanrequired
POST /{id}/item. False for the reasons update_address is, on live PrintedSimply orders (501 not_supported_by_provider), and on an order a shopper paid for (409 shopper_paid_order).
actions.update_itembooleanrequired
PUT /{id}/item/{itemId}. False for the reasons update_address is and on live PrintedSimply orders (501 not_supported_by_provider). An unchanged quantity is still an allowed no-op.
actions.cancel_itembooleanrequired
DELETE /{id}/item/{itemId}/cancel. False for the reasons update_address is.
tracking_tokenstring | nullrequired
The opaque token for this order's public tracking page; null until one is issued.
tracking_numberstring | nullrequired
The carrier's tracking number; null until the order ships.
tracking_carrierstring | nullrequired
The carrier that holds the shipment; null until the order ships.
tracking_urlstring | nullrequired
The carrier's own tracking URL; null until the order ships.
trackingobjectrequired
Where the parcel is. The same block on GET /v1/order/{id} and on every GET /v1/orders row. number, carrier and url are null until the order ships, and equal the flat tracking_number, tracking_carrier and tracking_url beside it. On a live order whose facility reports its own tracking object, that object's keys are kept and these are added where it has none.
tracking.numberstring | nullrequired
The carrier's tracking number; null until the order ships.
tracking.carrierstring | nullrequired
The carrier that holds the shipment; null until the order ships.
tracking.urlstring | nullrequired
The carrier's tracking link; null until the order ships.
tracking.page_urlstring (uri) | nullrequired
The order's hosted tracking page, the link to give your customer. It exists from the moment the order is placed and shows each step, including before the carrier has a number; the create response's tracking_url opens the same page. Null only on an order with no tracking token.
estimated_deliveryobject | nullrequired
When the order should arrive, as an estimate: the producing facility's production estimate plus the shipping method's transit window (our plant's standard parcel from the plant's own transit estimate), in business days counted in UTC, Monday to Friday, never on a day GET /calendar lists (the federal holidays, each on the weekday it is observed, and the plant's own closure days), counted from when the order was placed (when a person approved it, for an order placed with approval). The same function POST /orders/quote dates an order with, so it is the quote's estimated_delivery for the order as placed. Not a promise, and it does not move when an order runs late. Null on a lane that is not one of our own facilities (it sets its own times), on an order with no known shipping method, and whenever the order is not on its way: pending_approval, pending_payment, delivered, cancelled, issue_flagged, rerouting and every legacy status. Present (non-null) only on paid, accepted, in_production, quality_check and shipped.
estimated_delivery.earlieststring (date)required
YYYY-MM-DD, UTC: the soonest the order should arrive.
estimated_delivery.lateststring (date)required
YYYY-MM-DD, UTC: the latest it should, before anything goes wrong.
estimated_delivery.ships_bystring (date)required
YYYY-MM-DD, UTC: the day it should leave the facility, when its production estimate ends, counted the same way.
estimated_delivery.is_estimatebooleanrequired
Always true: say it as an estimate wherever it is shown.
Always true
reordered_fromstring | nullrequired
On an order POST /order/{id}/reorder placed: the source order's portal_order_id, the value the reorder's own answer stated. Null on any other order.
created_atstring (date-time)required
updated_atstring (date-time)required

meta

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.
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.
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.
totalinteger
Every row matching the request's filters, on the lists that count them (orders, an order's events, assets and products).
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.
pagesintegerdeprecated
total over limit, rounded up, beside page (orders and an order's events). Absent on a cursor walk.
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": [
    {
      "order_id": "test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
      "portal_order_id": "ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
      "provider": "printedsimply",
      "made_by": null,
      "guarantee": null,
      "reference": null,
      "vat": null,
      "landed_cost": null,
      "status": "paid",
      "issue_reason": null,
      "total": "$72.99",
      "shipping": "$8.99",
      "total_cents": 7299,
      "shipping_cents": 899,
      "is_test": true,
      "test_mode": true,
      "channel": "api",
      "drop_id": null,
      "items": [
        {
          "id": "itm_fowT5-1iZwSnQcGX0ByoA64l",
          "sku": "sticker-die-cut-3x3",
          "quantity": 100,
          "unit_price_cents": 64
        }
      ],
      "line_items": [
        {
          "id": "itm_fowT5-1iZwSnQcGX0ByoA64l",
          "sku": "sticker-die-cut-3x3",
          "quantity": 100,
          "unit_price_cents": 64
        }
      ],
      "actions": {
        "cancel": true,
        "update_address": true,
        "update_shipping": true,
        "upgrade_shipping": true,
        "add_item": true,
        "update_item": true,
        "cancel_item": true
      },
      "tracking_token": "trk_AquJFqDLDkisK6Jh-HABHz9L",
      "tracking_number": null,
      "tracking_carrier": null,
      "tracking_url": null,
      "tracking": {
        "number": null,
        "carrier": null,
        "url": null,
        "page_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfQXF1SkZxRExEa2lzSzZKaC1IQUJIejlMIn0.199c0c58721512fcccd784902c422ca4e827c6d09b7e495bbb4db9b06ae62003"
      },
      "estimated_delivery": {
        "earliest": "2026-10-20",
        "latest": "2026-10-26",
        "ships_by": "2026-10-14",
        "is_estimate": true
      },
      "reordered_from": null,
      "created_at": "2026-10-10T08:09:14.588Z",
      "updated_at": "2026-10-10T08:09:14.588Z"
    }
  ],
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a",
  "meta": {
    "page": 1,
    "pages": 1,
    "limit": 20,
    "total": 1,
    "has_more": false,
    "next_cursor": null
  }
}

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.
401
Unauthorized — invalid or missing API key
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

statusquery · string

Filter by order status. An unknown value is refused with 400 validation_error, never ignored — an unrecognised status would otherwise match no row and answer 200 with an empty page, which is indistinguishable from having no such orders. Current statuses: pending_approval, pending_payment, paid, accepted, in_production, quality_check, shipped, delivered, cancelled, issue_flagged, rerouting. Historical values, accepted so orders older than this vocabulary stay reconcilable but no longer written: pending, processing, on-hold, completed, refunded, failed.

One of pending_approval pending_payment paid accepted in_production quality_check shipped delivered cancelled issue_flagged rerouting pending processing on-hold completed refunded failed

referencequery · string

Exact match on the reference you supplied at create. Use it to reconcile your own order ids against ours — including after a create response you never received.

fromquery · string (date-time)

Filter orders created on or after this date. A value that is not a date, or a from later than to, returns 400 validation_error — it is never dropped, because an unfiltered page is indistinguishable from a windowed one.

toquery · string (date-time)

Filter orders created on or before this date. A value that is not a date returns 400 validation_error.

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 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

Orders per page: 20 by default, 100 at most. A value above 100 is clamped to 100 and one below 1 to 1, a fraction is truncated, and a missing, zero or non-numeric value falls back to 20; none is refused.

Default 20

pagequery · integerdeprecated

Deprecated: walk with cursor. The page number of the offset walk this operation always had, answered as before (limit 20 by default, 100 at most; offset, a row count, is accepted in its place). An order written while you page shifts every offset behind it; a cursor cannot be shifted. Ignored when cursor is sent, and a cursor walk's meta carries no page or pages.

Default 1

Response 200

data is a list; each entry:

order_idstringrequired
The fulfilment network's order id — the one GET /v1/order/{id} and every other order operation take.
portal_order_idstringrequired
This platform's own id for the order.
providerstringrequired
The fulfilment lane that holds the order.
made_byobject | nullrequired
The independent network shop that produced an order, or null when an in-house lane did. GET /v1/orders and GET /v1/order/{id} build it from the same helper and both $ref this, so they cannot describe one fact two ways — which they did, one of them calling it a string. Every order placed on this portal is made at our own plant, so it is null on them; a shop is named only on an order placed before that.
made_by.namestringrequired
The shop's display name.
made_by.slugstringrequired
The shop's directory slug.
made_by.profile_urlstring (uri)required
Its public profile page on this platform.
guaranteeobject | nullrequired
The delivery guarantee in force on this order, or null when the order carries none (guarantees are issued only on lanes whose measured on-time record clears the floor, and only while the feature is enabled). The keys mirror the guarantee block returned by POST /orders/quote, so this is the object you were quoted, read back, plus what has since happened to it.
guarantee.guarantee_idstringrequired
Same id the quote issued.
guarantee.deliver_bystring (date-time)required
The date this order is guaranteed to arrive by.
guarantee.quality_standardstringrequired
The quality standard guaranteed ("standard" in v1).
guarantee.confidencenumberrequired
Lower bound on the lane's on-time probability at issue time (Wilson), between 0 and 1.
guarantee.remedyobjectrequired
The promise. cap_cents is the ceiling on what a breach can pay — never an amount owed or paid; read remedies for what was actually recorded.
guarantee.remedy.typestringrequired
credit is the only remedy issued today, and the one that settles as a real refund. remake and expedite are reserved for the ops-driven remedies; one would settle as not_applicable rather than pay.
One of credit remake expedite
guarantee.remedy.cap_centsintegerrequired
guarantee.statusstringrequired
issued while the promise is open, honored once the order was delivered on time, remedied once it was not. There is deliberately no breached value: a breach and its capped remedy are recorded in one transaction (so two overlapping sweeps cannot both pay out), so the terminal state of a broken promise is remedied and whether the money moved is the remedy's own status.
One of issued honored remedied
guarantee.issued_atstring (date-time)required
guarantee.resolved_atstring (date-time) | nullrequired
When the guarantee was honored or remedied; null while still open.
guarantee.remediesobject[]required
Remedies recorded against this guarantee. Empty unless it was breached.
guarantee.remedies[].typestringrequired
One of credit remake expedite
guarantee.remedies[].amount_centsintegerrequired
What was recorded, capped at the order value at issue.
guarantee.remedies[].statusstringrequired
applied is the only value that means money moved — a real refund on the order's charge. not_applicable is the ordinary sandbox outcome (a test order has no charge) and also covers a remake/expedite, which is an ops action rather than an automatic payment. failed is an owed remedy that has not been paid, kept distinct from not_applicable so it stays visible.
One of pending applied failed not_applicable
guarantee.remedies[].applied_atstring (date-time) | nullrequired
guarantee.remedies[].created_atstring (date-time)required
referencestring | nullrequired
The reference you supplied at creation, echoed back. Null on orders placed without one, and on every order that predates the column.
vatstring | nullrequired
The tax-registration number declared on this order; null when none was supplied.
landed_costobject | nullrequired
What the border cost on this order, as recorded for the parcel that ships. Null on a domestic shipment — there is no border, so there is nothing to state, and a row of zeros would read like a customs assessment that came to nothing. When a cross-border order has no stored figures, recorded is false and only destination_country and not_recorded_reason are present: the duty, tax and FX rates that applied on the day are not recoverable, and backfilling them with today's rates would be a fabricated record rather than a missing one. That is what an order placed before these figures were stored looks like, and also a free replacement order, which carries no charged goods value to assess. The figures are a snapshot, never recomputed on read, so a stale figure cannot be mistaken for a current one — but they ARE re-recorded when the parcel itself changes, because the border is costed against the destination, the goods and the shipping charge. Change the address, add or cancel a line, change a quantity or change the shipping method and the order is costed again at that moment; recorded_at moves with it, and it is the order's creation time until something does. An order re-routed to a domestic address goes back to null. estimated stays true throughout: on DAP the courier bills the recipient directly, so we never learn what customs actually assessed.
landed_cost.recordedbooleanrequired
False when no landed cost was stored for this order.
landed_cost.destination_countrystring
ISO 3166-1 alpha-2.
landed_cost.not_recorded_reasonstring
Present only when recorded is false.
landed_cost.recorded_atstring (date-time)
When the figures were computed — never the moment of the read. The order's creation time, or the moment of the last change to its destination, lines or shipping charge.
landed_cost.duty_basisstring
DAP today: goods and shipping are collected at checkout, and the courier bills the recipient for duties and import tax on delivery.
One of DDP DAP
landed_cost.duty_ratenumber
landed_cost.tax_ratenumber
landed_cost.breakdownobject
landed_cost.breakdown.goods_centsinteger
landed_cost.breakdown.shipping_centsinteger
landed_cost.breakdown.duties_centsinteger
landed_cost.breakdown.tax_centsinteger
landed_cost.total_landed_centsinteger
What the buyer ends up paying in total.
landed_cost.pre_collected_centsinteger
Collected at checkout. Equals goods + shipping — never more than was charged.
landed_cost.due_on_delivery_centsinteger
Billed by the courier on delivery. Sums with pre_collected_cents to the total.
landed_cost.presentmentobject
landed_cost.presentment.currencystring
landed_cost.presentment.amount_centsinteger
landed_cost.presentment.minor_unitsinteger
landed_cost.presentment.fx_ratenumber
landed_cost.estimatedboolean
landed_cost.notestring
statusstringrequired
The order's lifecycle status, from the same vocabulary the status filter above accepts.
One of pending_approval pending_payment paid accepted in_production quality_check shipped delivered cancelled issue_flagged rerouting pending processing on-hold completed refunded failed
issue_reasonstring | nullrequired
Why the order is issue_flagged, as GET /v1/order/{id} reports it; null when it is not flagged, or no reason fits.
One of artwork_unprintable address_undeliverable shipment_exception on_hold cancellation_pending
totalstringrequired
What the order was charged, formatted for display — a dollar string such as $42.00, NOT an integer of cents. total_cents beside it carries the same money as an integer, under the name GET /v1/order/{id} uses; read that one. Kept because the shape is published and changing it would break every caller reading it.
shippingstringrequired
The shipping charge, formatted the same way as total; shipping_cents is the same money in cents.
total_centsintegerrequired
What the order was charged, in cents — the same money as total, and the same field GET /v1/order/{id} carries.
shipping_centsintegerrequired
The shipping charge, in cents — the same money as shipping.
is_testbooleanrequired
True on a sandbox order. The same value as test_mode beside it; kept because it is published.
test_modebooleanrequired
True on a sandbox order, false on a live one — is_test under the name the create response and GET /v1/order/{id} use. Present on every row here (the order read omits it on a live order).
channelstringrequired
The surface that placed the order. On hosted, acp and ucp a shopper paid your store, and total is that sale; on every other channel you placed the order and total is what it cost you. unknown is an order older than the record.
One of acp ucp mcp verified_agent oauth_app api dashboard autopilot hosted storefront unknown
drop_idstring | nullrequired
The drop a shopper bought this order on; null on an order no drop sold.
itemsobject[]required
The order's lines. Each carries the id our item and return operations resolve — see OrderLine.
items[].idstringrequired
This line's id. Use it as {itemId} on PUT /v1/{id}/item/{itemId} and DELETE /v1/{id}/item/{itemId}/cancel.
items[].skustringrequired
items[].quantityintegerrequired
at least 1
items[].unit_price_centsintegerrequired
items[].artworkobject
The line's artwork declaration, as the order accepted it: how the artwork was made, and who approved it and when. Absent on a line that declared none.
items[].artwork.provenancestring
How the artwork was made: human (made by a person), ai_assisted (a person made it with a model's help) or ai_generated (a model made it).
One of human ai_assisted ai_generated
items[].artwork.approved_bystring
Who approved the artwork for print: a name or an email address, at most 200 characters. Control and invisible formatting characters are removed and whitespace collapsed before it is stored. Send it with approved_at.
non-empty · at most 200 characters
items[].artwork.approved_atstring (date-time)
When the artwork was approved: an ISO 8601 date-time with a time zone, not in the future. Stored and echoed in UTC. Send it with approved_by.
line_itemsobject[]required
The same lines as items, under the name GET /v1/order/{id} publishes them as, so one name reads the lines from either.
The same fields as items
actionsobjectrequired
Which changes this order still takes, read from the same checks the operations refuse on, so a client can show or offer an action without trying it first. true means the order's own state does not refuse it; the request is still checked as usual (the key's scope; the line an item action names, which must exist and, on a live order at our own plant, carry its artwork; and on a live order the facility, which can refuse a change with 502 fulfillment_error). false names the refusal the operation would give. Live PrintedSimply orders have add_item, update_item and upgrade_shipping false; only supported no-cost or downward shipping requests remain requestable. On other orders a shopper paid for (a drop, a checkout link or an agent checkout), update_item and update_shipping stay true because a decrease or a downgrade is allowed, while an increase or an upgrade is refused 409 shopper_paid_order, as add_item is.
actions.cancelbooleanrequired
DELETE /order/{id}/cancel. True only before production (pending_payment, paid or accepted); false once the order is cancelled (400 already_cancelled) or past that (409 not_cancellable).
actions.update_addressbooleanrequired
PUT /order/{id}/address. False on an order an independent shop made (501 not_supported_by_provider) and once the order is past the point of change (409 order_not_modifiable).
actions.update_shippingbooleanrequired
PUT /order/{id}/shipping. False for the reasons update_address is.
actions.upgrade_shippingbooleanrequired
Positive-cost PUT /order/{id}/shipping upgrades. False for live PrintedSimply orders (501 not_supported_by_provider), shopper-paid orders (409 shopper_paid_order), and when update_shipping is false. A downgrade or unchanged method can still be allowed when this is false.
actions.add_itembooleanrequired
POST /{id}/item. False for the reasons update_address is, on live PrintedSimply orders (501 not_supported_by_provider), and on an order a shopper paid for (409 shopper_paid_order).
actions.update_itembooleanrequired
PUT /{id}/item/{itemId}. False for the reasons update_address is and on live PrintedSimply orders (501 not_supported_by_provider). An unchanged quantity is still an allowed no-op.
actions.cancel_itembooleanrequired
DELETE /{id}/item/{itemId}/cancel. False for the reasons update_address is.
tracking_tokenstring | nullrequired
The opaque token for this order's public tracking page; null until one is issued.
tracking_numberstring | nullrequired
The carrier's tracking number; null until the order ships.
tracking_carrierstring | nullrequired
The carrier that holds the shipment; null until the order ships.
tracking_urlstring | nullrequired
The carrier's own tracking URL; null until the order ships.
trackingobjectrequired
Where the parcel is. The same block on GET /v1/order/{id} and on every GET /v1/orders row. number, carrier and url are null until the order ships, and equal the flat tracking_number, tracking_carrier and tracking_url beside it. On a live order whose facility reports its own tracking object, that object's keys are kept and these are added where it has none.
tracking.numberstring | nullrequired
The carrier's tracking number; null until the order ships.
tracking.carrierstring | nullrequired
The carrier that holds the shipment; null until the order ships.
tracking.urlstring | nullrequired
The carrier's tracking link; null until the order ships.
tracking.page_urlstring (uri) | nullrequired
The order's hosted tracking page, the link to give your customer. It exists from the moment the order is placed and shows each step, including before the carrier has a number; the create response's tracking_url opens the same page. Null only on an order with no tracking token.
estimated_deliveryobject | nullrequired
When the order should arrive, as an estimate: the producing facility's production estimate plus the shipping method's transit window (our plant's standard parcel from the plant's own transit estimate), in business days counted in UTC, Monday to Friday, never on a day GET /calendar lists (the federal holidays, each on the weekday it is observed, and the plant's own closure days), counted from when the order was placed (when a person approved it, for an order placed with approval). The same function POST /orders/quote dates an order with, so it is the quote's estimated_delivery for the order as placed. Not a promise, and it does not move when an order runs late. Null on a lane that is not one of our own facilities (it sets its own times), on an order with no known shipping method, and whenever the order is not on its way: pending_approval, pending_payment, delivered, cancelled, issue_flagged, rerouting and every legacy status. Present (non-null) only on paid, accepted, in_production, quality_check and shipped.
estimated_delivery.earlieststring (date)required
YYYY-MM-DD, UTC: the soonest the order should arrive.
estimated_delivery.lateststring (date)required
YYYY-MM-DD, UTC: the latest it should, before anything goes wrong.
estimated_delivery.ships_bystring (date)required
YYYY-MM-DD, UTC: the day it should leave the facility, when its production estimate ends, counted the same way.
estimated_delivery.is_estimatebooleanrequired
Always true: say it as an estimate wherever it is shown.
Always true
reordered_fromstring | nullrequired
On an order POST /order/{id}/reorder placed: the source order's portal_order_id, the value the reorder's own answer stated. Null on any other order.
created_atstring (date-time)required
updated_atstring (date-time)required

meta

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.
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.
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.
totalinteger
Every row matching the request's filters, on the lists that count them (orders, an order's events, assets and products).
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.
pagesintegerdeprecated
total over limit, rounded up, beside page (orders and an order's events). Absent on a cursor walk.
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": [
    {
      "order_id": "test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
      "portal_order_id": "ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
      "provider": "printedsimply",
      "made_by": null,
      "guarantee": null,
      "reference": null,
      "vat": null,
      "landed_cost": null,
      "status": "paid",
      "issue_reason": null,
      "total": "$72.99",
      "shipping": "$8.99",
      "total_cents": 7299,
      "shipping_cents": 899,
      "is_test": true,
      "test_mode": true,
      "channel": "api",
      "drop_id": null,
      "items": [
        {
          "id": "itm_fowT5-1iZwSnQcGX0ByoA64l",
          "sku": "sticker-die-cut-3x3",
          "quantity": 100,
          "unit_price_cents": 64
        }
      ],
      "line_items": [
        {
          "id": "itm_fowT5-1iZwSnQcGX0ByoA64l",
          "sku": "sticker-die-cut-3x3",
          "quantity": 100,
          "unit_price_cents": 64
        }
      ],
      "actions": {
        "cancel": true,
        "update_address": true,
        "update_shipping": true,
        "upgrade_shipping": true,
        "add_item": true,
        "update_item": true,
        "cancel_item": true
      },
      "tracking_token": "trk_AquJFqDLDkisK6Jh-HABHz9L",
      "tracking_number": null,
      "tracking_carrier": null,
      "tracking_url": null,
      "tracking": {
        "number": null,
        "carrier": null,
        "url": null,
        "page_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfQXF1SkZxRExEa2lzSzZKaC1IQUJIejlMIn0.199c0c58721512fcccd784902c422ca4e827c6d09b7e495bbb4db9b06ae62003"
      },
      "estimated_delivery": {
        "earliest": "2026-10-20",
        "latest": "2026-10-26",
        "ships_by": "2026-10-14",
        "is_estimate": true
      },
      "reordered_from": null,
      "created_at": "2026-10-10T08:09:14.588Z",
      "updated_at": "2026-10-10T08:09:14.588Z"
    }
  ],
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a",
  "meta": {
    "page": 1,
    "pages": 1,
    "limit": 20,
    "total": 1,
    "has_more": false,
    "next_cursor": null
  }
}

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.

401

Unauthorized — invalid or missing API key

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.

List orders

Parameters

Request

Response 200

Errors

List orders

Parameters

Request

Response 200

Errors

Response `200`

Response `200`