Reference · API reference

Reference

API reference

Every operation in the PrintedSimply API — orders, products, pricing, shipping, artwork, and webhooks. Open one for its parameters, request body, response, scopes and errors, and the same request in curl, TypeScript, Python and PHP.

Base URL

All API requests are made to the following base URL:

https://portal.printedsimply.com/api/v1

Every path below is relative to it: /order means https://portal.printedsimply.com/api/v1/order. Answers are JSON, in the envelope described below.

Every operation below is also in the Postman collection (with these bodies and a fresh Idempotency-Key on each write) and the OpenAPI document this page is read from.

Import into Postman, Insomnia or Bruno

Each takes the API from a URL, so there is no file to keep up to date: import again to pick up a change.

Postman collection

https://portal.printedsimply.com/api/postman-collection

OpenAPI document

https://portal.printedsimply.com/api/openapi.json

Postman: choose Import and paste the collection's URL. Each request comes with its example body, a fresh Idempotency-Key on each write, and the ids one request hands the next. Set the collection's apiKey variable to your test key.
Insomnia: choose Import, pick URL, paste either URL and choose Scan.
Bruno: choose +, then Import Collection, and enter the OpenAPI document's URL (Bruno takes a Postman collection as a downloaded file).

Every request sends your key in x-api-key; a test key places $0 orders.

Authentication

Send your API key in the x-api-key header:

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

Test keys start with ps_test_ and live keys with ps_live_. A test key places $0 orders that run the whole lifecycle. Keys created before the PrintedSimply rename start with mf_test_ or mf_live_ and keep working, in the same mode.
Manage your keys in the API Keys dashboard. A key made with a scope list may call only the operations whose scopes it holds; each operation names its own.
Requests without a valid key return 401 Unauthorized.

Key format, and the patterns a secret scanner matches

Key format: the prefix, then 38 base62 characters (0-9, A-Z, a-z): 32 random, then a 6-character checksum. The checksum is the CRC-32 (IEEE) of the 32 random characters, written in base62, most significant digit first, padded with 0 to six. A key in that shape whose checksum fails, a typo for instance, is refused with 401 invalid_api_key before any lookup. The checksum is the same under either prefix, so it holds for an mf_ key too. A secret scanner matches a key, under either prefix, with:

Regular expression

\b(?:ps|mf)_(?:live|test)_[0-9A-Za-z]{38}\b

Keys created before the checksum was added (32 characters after the prefix, which may include _ and -) keep working, but that pattern does not match them. Rotating an older key gives one it matches; until then, this one matches the older shape:

Regular expression (older keys)

\bmf_(?:live|test)_[0-9A-Za-z_-]{32}(?![0-9A-Za-z_-])

Create an order

One request places an order: POST /order with the lines, the address and how to ship it. With a test key it costs $0 and runs end to end.

POST /api/v1/order

curl -X POST https://portal.printedsimply.com/api/v1/order \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-$(date +%s)" \
  -d '{
    "items": [
      { "sku": "sticker-die-cut-3x3", "quantity": 100,
        "artwork_url": "https://printedsimply.com/samples/sticker-3x3.png" }
    ],
    "address_to": {
      "name": "Jane Doe", "address1": "123 Main St",
      "city": "Austin", "state": "TX", "zip": "78701", "country": "US"
    },
    "shipping": { "method": "standard" }
  }'

Required: address_to (name, address1, city, state, zip, country), items (sku, quantity). The rest is optional, and every field is described under the operation.
Send an Idempotency-Key: a retry with the same key and body returns the first answer instead of placing a second order.
The answer's order_id is the order (a test_ord_ id on a test key). Read it back with GET /order/{id}, and on a test key move it along with POST /order/{id}/simulate.

Discovery

The base URL itself answers without a credential, so a client can find the machine-readable spec before it has a key.

GET/API index (public discovery)GET/meDescribe the calling credential GET/setupDescribe what this account still needs

Orders

GET/ordersList orders POST/orderCreate an order GET/order/{id}Get order details DELETE/order/{id}/cancelCancel an order PUT/order/{id}/addressUpdate shipping address PUT/order/{id}/shippingUpdate shipping method GET/order/{id}/eventsGet order events GET/order/{id}/timelineGet an order's timeline POST/order/{id}/missing-letterReport a missing letter and reship it once POST/order/{id}/reorderPlace an order again POST/order/{id}/simulateForce a sandbox order to a lifecycle state GET/orders/exportExport orders as CSV POST/orders/bulkCreate bulk orders POST/orders/multi-shipCreate multi-address order

Artwork is read before the charge: on a sticker, decal, magnet or poster line, the file behind artwork_url or print_file is graded against the line's print size. A live order whose file is gone, is not an image, or is too small to print at that size is refused with 422 artwork_not_printable, naming each line and the pixels it needs, and nothing is charged. A live line with no file at all is refused first, with 422 artwork_required naming the line. A file we could not read just now never refuses an order. The answer carries those lines' verdicts in artwork_check; a test key is never refused for artwork, and would_refuse says whether a live order would be.

A different name on every sticker: an item of a flat-goods line made at our own plant may carry variable_data, the named slots of its design and a value for each slot on every unit, from a units array (one entry per unit), a number sequence, or both, plus an optional QR payload template. The quote and the order preflight it before anything is charged and refuse an overflow, a count mismatch or an unknown slot with 422 variable_data_invalid; both answer with the first, last and longest unit as proofs. It never changes the price. Test keys run it end to end; live orders carrying it are refused with variable_data_unavailable until production is switched on.

Order items

Item paths are relative to an order id, e.g. /{id}/item.

POST/{id}/itemAdd item to order PUT/{id}/item/{itemId}Update item quantity DELETE/{id}/item/{itemId}/cancelRemove item from order

Products

GET/productsList products GET/products/{sku}Get product by SKU GET/products/optionsList what a custom size may be POST/products/recommendGet product recommendations

Pricing

POST/orders/quoteGet a signed, expiring price quote GET/pricing/tiersGet plan tiers POST/pricing/estimateGet pricing estimate

Shipping

POST/shipping/estimateEstimate shipping costs GET/calendarList the days no delivery estimate counts POST/addresses/validateCheck a shipping address

Artwork & mockups

POST/artwork/validateValidate artwork file POST/mockups/generateGenerate product mockup

Assets

GET/assetsList your uploaded assets POST/assetsUpload an asset (base64)GET/assets/{id}Get an asset DELETE/assets/{id}Delete an asset

Webhooks

Webhook endpoints are managed with your API key — register them, rotate their signing secrets, inspect deliveries, and replay a failed one, all without opening a browser. The same subscriptions appear in your dashboard.

PrintedSimply signs every delivery twice. Verify X-PS-Signature-V2 (t=<unix>,v1=<hex>), which signs the timestamp with the body so a replayed request can be refused; X-PS-Signature (sha256=<hex>) is the original, body-only one.

GET/webhooksList webhook subscriptions POST/webhooksCreate a webhook subscription GET/webhooks/{id}Retrieve a webhook subscription PATCH/webhooks/{id}Update a webhook subscription DELETE/webhooks/{id}Delete a webhook subscription POST/webhooks/{id}/rotate-secretRotate a webhook signing secret DELETE/webhooks/{id}/rotate-secretEnd an open rotation window POST/events/{eventId}/replayReplay a stored event to your webhooks GET/webhooks/deliveriesList webhook delivery attempts GET/webhooks/deliveries/{id}Retrieve a webhook delivery POST/webhooks/deliveries/{id}/redeliverReplay a webhook delivery GET/webhooks/inboxRead the hosted test inbox POST/webhooks/inboxCreate the hosted test inbox DELETE/webhooks/inbox/entriesEmpty the hosted test inbox

A webhook needs a public URL to POST to. If you do not have one — a script in a notebook, a job behind NAT — pull the same events instead. This is also how a subscriber catches up after being down longer than the retry ladder: event_id is the same value as the X-PS-Event-Id header, so you can dedupe across both. Events are kept 30 days.

GET/eventsList account events

See the Webhooks guide for event types, signature verification, and retry policies.

Common response format

A success comes back in one envelope: status, the operation's data, and the request_id (also the X-Request-Id header) to quote when you write to us. A list returns its rows in data and how to page on in meta (Pagination). As the document's own examples give them:

{
  "status": "success",
  "data": {
    "order_id": "test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
    "portal_order_id": "ord_wVK9ZiG-VYiPrlSeBUBmrUVk",
    "status": "shipped",
    "simulated": true
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

The discovery index and a CSV export are the exceptions: each operation says what it answers with.

Error handling

An error carries an HTTP status and a structured body: branch on error.code, never the message. Here POST /api/v1/order was sent a line of quantity 0 and no address, and details.fieldErrors names each field it refused:

POST /api/v1/order → 400

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation.",
    "doc_url": "https://portal.printedsimply.com/docs/errors#validation_error",
    "suggestion": "Check the details field for specific validation failures. Refer to the endpoint reference for required fields.",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "address_to": [
          "Invalid input: expected object, received undefined"
        ],
        "items": [
          "Quantity must be at least 1"
        ]
      },
      "errors": [
        {
          "pointer": "/address_to",
          "code": "invalid_type",
          "message": "Invalid input: expected object, received undefined"
        },
        {
          "pointer": "/items/0/quantity",
          "code": "too_small",
          "message": "Quantity must be at least 1"
        }
      ]
    }
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

Every status the API answers with (14), and the codes each can carry

200OK — the request did what it asked.
400Bad request — the body or a parameter did not validate; nothing was done.
validation_error already_cancelled pricing_error unknown_sku test_mode_only already_terminal event_not_available
401Unauthorized — no credential, or one that is invalid, expired or revoked.
invalid_api_key missing_api_key key_expired
402Payment required — the charge was refused or a spend cap stopped it; nothing was charged.
no_payment_method payment_failed authentication_required fraud_review spend_cap_exceededspend_cap_unenforceable
403Forbidden — the credential cannot do this (its scope, its mode, or the account's).
sandbox_only insufficient_scope live_key_required
404Not found — nothing of that id on this account.
order_not_found
409Conflict — the resource's state does not allow it any more.
duplicate_reference idempotency_conflict not_cancellable already_cancelled production_reconciliation_required order_not_modifiable shopper_paid_order letter_report_refused invalid_state concurrent_modification cursor_source_changed
413Payload too large — the body is over this operation's byte cap; it was not read.
payload_too_large
422Unprocessable — a valid request the API refuses for what it asks; the code says why.
variable_data_invalid variable_data_unavailable artwork_not_printable artwork_required destination_unavailable below_cost_floor address_invalidmax_provider_cost_requiredsku_not_available provider_not_available
429Too many requests — a rate window or the daily quota; wait for Retry-After.
rate_limit_exceeded daily_quota_exceeded
500Server error — the code says whether anything happened; some must not be retried.
internal_error order_error refund_failed
501Not implemented — whoever makes this order does not support the change.
not_supported_by_provider
502Bad gateway — the production system did not answer or refused.
fulfillment_error internal_error
503Unavailable — the service it needs is not taking requests right now.
provider_unavailable pricing_error unknown_sku reference_check_unavailable idempotency_unavailable

See the full error reference for all error codes and their meanings.

Pagination

A list that returns next_cursor pages by cursor: ask for a page, then send the next_cursor it returned as cursor until it comes back null — on a list whose meta is ListMeta, until meta.has_more is false. Pass a cursor back unchanged: it works only on the list, the account and the key mode it was returned to.

curl "https://portal.printedsimply.com/api/v1/orders?limit=50&cursor=NEXT_CURSOR" \
  -H "x-api-key: ps_test_YOUR_KEY"

GET /orders (meta.next_cursor), GET /order/{id}/events (meta.next_cursor), GET /order/{id}/timeline (meta.next_cursor), GET /products (meta.next_cursor), GET /events (data.next_cursor), GET /assets (data.next_cursor), GET /webhooks (data.next_cursor), GET /webhooks/deliveries (data.next_cursor), GET /webhooks/inbox (meta.next_cursor).

These also take a page number, deprecated where the list pages by cursor and answered as before: page (from 1) with limit, and say where they are in meta (page, pages, total):

GET /orders, GET /order/{id}/events, GET /products, GET /assets.

Reliability contract · Rate limits · Webhooks · Error reference · Email us at developers@printedsimply.com