Get pricing estimate

Parameters

• Idempotency-Keyheader · string (uuid)

  Unique key for idempotent requests. If you retry a request with the same key within 24 hours, you receive the original response. The key is bound to the request payload: reusing it for a different payload returns 422 idempotency_key_reuse rather than the original response, so a changed request is never silently dropped. The binding is over the JSON's content, not its bytes — keys in another order or other whitespace are the same request. Generate a new key for each new request. On an operation that moves money (an order, a batch, an item, a shipping or address change, a cancellation's refund), a key that cannot be checked because the idempotency ledger is unreachable is answered 503 idempotency_unavailable with Retry-After, and nothing runs or is charged: retry with the same key.

Request body application/json, required

• itemsobject[]required

  At most 100 lines of at most 10,000 units each, the bounds POST /order takes.

  1 to 100 entries

• items[].skustringrequired

  non-empty

• items[].quantityintegerrequired

  1 to 10000

• shipping_methodstring

  One of standard priority express letter

  Default standard

• destination_countrystring

  ISO-3166-1 alpha-2. Optional. This estimate prices our own facilities' lanes, which ship to US addresses only, so any other country is refused 422 destination_unavailable.

  exactly 2 characters

Request

curl -X POST "https://printedsimply.com/api/v1/pricing/estimate" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: estimate-pricing-$(date +%s)" \
  -d '{
    "items": [
      {
        "sku": "sticker-die-cut-3x3",
        "quantity": 100
      }
    ],
    "shipping_method": "standard"
  }'

Response 200

{
  "status": "success",
  "data": {
    "items": "$70.00",
    "shipping": "$8.99",
    "processing_fee": "$0.00",
    "platform_fee": "$0.00",
    "card_fee": "$0.00",
    "total": "$78.99",
    "total_cents": 7899
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

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_keymissing_api_keykey_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).

• 413payload_too_large

  payload_too_large — the request body exceeded this route's byte cap (256 KB unless the route raises it with a written reason). It is refused before it is parsed, so nothing was created. Send fewer rows, or use the endpoint's own asynchronous door where it has one.

• 422destination_unavailablebelow_cost_floorsku_not_orderable_yetsku_not_availablecatalog_onlyshipment_capacity_exceeded

  destination_unavailable — the destination is outside the US, and this estimate prices our own lanes only: our own facilities ship to US addresses only. details.reason is destination_not_us and details.country names the destination. below_cost_floor — the order would be made at our own plant and would cost more to make and ship than it is charged, at worst-case postage, and its loss is not one our cost floor accepts: only today's named losses are, no larger than they are today — the flat standard parcel under its postage, for a mailer up to a pound or a poster tube up to two, and list-priced goods short only of the per-order handling cost (or a partner SKU would be charged below what the partner bills for it). details.skus names the items and details.contribution_cents how far below zero the order falls. Nothing was charged; add units, combine it with another order, or choose another shipping method on offer. sku_not_orderable_yet — live keys only: a line names a modeled product our catalog lists that our plant has not confirmed it makes yet. details.skus names them as sent, and details.plant_skus the spelling our plant adopts for one sent another way. Refused before anything is asked of the plant or charged; a test key orders a modeled listing at its listed price. catalog_only — a flag or Santa hat is a catalog reference whose artwork, production cost and shipping weight are unconfirmed. Automatic quotes and orders are refused in both test and live mode before pricing, routing or charging, including requests carrying an earlier quote; details.skus, details.readiness and details.reason explain the refusal. shipment_capacity_exceeded — a basket of sized own-plant products exceeds the modeled 70 lb single-parcel limit, including stickers, magnets, posters, decals, packs and rolls. Both test and live requests are refused before charging; details.skus, details.weight_oz and details.max_weight_oz state the affected SKUs, whole-basket estimated weight and limit. Reduce the quantity or split the order. sku_not_available — a line names a product our own plant does not make: only PrintedSimply's own products (stickers, decals, labels, magnets and posters, as GET /products lists them) are sold here. details.skus names each one. Asked before anything is priced, so nothing was priced or charged.

• 429rate_limit_exceededdaily_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.

• 503provider_unavailableunknown_sku

  provider_unavailable — no configured facility can produce these items, or (details.reason: plant_unreachable, with Retry-After) our plant gave no answer about a SKU — the request did not reach it, timed out, or came back 5xx, which is about the plant and not the SKU. Live keys; a test key gets a $0 estimate flagged pricing_degraded instead (provider_unavailable for an unconfigured facility, pricing_unavailable for an unanswering plant). Only for a SKU the catalog has, though: one the price book does not price, our plant's products do not name and the synced catalog does not hold is refused 400 unknown_sku with details.skus, as it is on POST /order, POST /orders/quote and POST /pricing/estimate alike.