Estimate shipping costs

POST/shipping/estimate

Calculate shipping options with costs and estimated delivery dates for a set of items to a destination. Does not create an order. Each option's cost_cents is the figure the order path will charge for that method: shipping is charged per parcel, never per item, at the class the items' estimated weight puts the parcel in (shipping_class): $8.99 up to 1 lb, $13.99 to 2 lb, $20.99 to 5 lb, $4.69 a pound above, $5.20 more for a tube (posters and wall decals), and 55¢ more on parcels from 2026-10-04 to 2027-01-16, each bare. Items made at the partner facility (apparel, mugs) ship at the larger of that class rate and the partner's own estimate for the parcel, and the option quotes that same figure: the partner's answer for a basket is reused for five minutes, so an order placed in that window is charged what this quoted. A hundred 3×3 stickers and one ship for the same price. Like a product price, it carries no platform fee and is the same on every plan, as the order path charges it. shipping_address decides which destination the estimate is echoed for; address_to, the name every order operation gives the destination, is accepted in its place, so the address you will order to can be sent as it is. One of the two is required, and both is a 400 validation_error when they name different destinations. Our own facilities ship to US addresses only, so a country other than US is refused 422 destination_unavailable. options lists only the methods on offer: standard always, priority and express once they are priced.

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

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 least 1 entry
items[].skustringrequired
non-empty
items[].product_idinteger
Catalog product ID
items[].quantityintegerrequired
at least 1
items[].sizestring
Product size (e.g. S, M, L, XL)
items[].colorstring
Product color
shipping_addressobject
Where the parcel goes. Only country decides the price (the rate depends on the method and the parcel's weight class, not the zone), so a country-only address is a complete request; zip is echoed back in destination when given. state and zip also decide which carrier advisories touch the destination (delivery_risk, deliver_by_check.status): a destination given by country alone is touched by every one. Required unless address_to is sent.
shipping_address.statestring
shipping_address.zipstring
Optional. Echoed back as destination.zip; null in the response when omitted.
non-empty
shipping_address.countrystring
Default US
address_toobject
The same destination under the name POST /order gives it, so the order's own address_to can be sent as it is: only state, zip and country are read, and the rest is ignored. Send this or shipping_address; both are accepted only when every field they both give agrees (the country defaults to US), and otherwise refused 400 validation_error.
address_to.statestring
address_to.zipstring
Optional. Echoed back as destination.zip; null in the response when omitted.
non-empty
address_to.countrystring
Default US
deliver_bystring (date)
A day the order should arrive by, YYYY-MM-DD (UTC). Answered in deliver_by_check, judged against the estimate's latest day rather than its earliest, from the facility's production estimate and the method's transit window. Optional; a day before today, or anything but a real date, is 400 validation_error.

Request

Try it

POST /api/v1/shipping/estimate

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

Response `200`

Every method, priced per PARCEL rather than per item, with business-day windows.

data

destinationobjectrequired
Echoed, not priced from.
destination.zipstring | nullrequired
Null when the caller estimated by country alone.
destination.countrystringrequired
total_itemsintegerrequired
Units across the request. The cost is per parcel regardless.
shipping_classobject
The parcel these items pack into, which prices every parcel option: a weight band (parcel_1lb, parcel_2lb, parcel_5lb, parcel_over_5lb), with _tube when a poster or wall decal ships rolled. Estimated from the items' print area, not weighed.
shipping_class.namestringrequired
shipping_class.weight_oznumberrequired
Estimated shipped weight in ounces, packing tube included.
optionsobject[]required
options[].methodstringrequired
The shipping tiers this platform prices. Per parcel, not per item: standard by the parcel's weight class (POST /v1/shipping/estimate reports it), and for items made at the partner facility (apparel, mugs) at the larger of that and the partner's own estimate for the parcel; priority and express at their price and never below standard for the same parcel. An unrecognised value is refused with 400 validation_error rather than priced as standard. standard is always offered; priority and express are offered when priced (each at or above the USPS cost of the service), and until then a request for either is refused 400 shipping_method_unavailable, with details.offered naming the methods that are, and nothing is charged. letter is untracked letter mail for stickers and small vinyl decals from our own plant, offered only where the platform prices it, for an order whose every item qualifies, within a unit and an order-value ceiling: otherwise a request for it is refused 400 letter_mail_unavailable with details.reason, and nothing is charged. On the API it is never chosen for you — no default, estimate or storefront mapping picks it — and it is placed through POST /v1/order only (bulk and bundle orders ship by parcel). A hosted store is the one exception, and only where its merchant turned on small orders by letter in the dashboard's store editor (off by default, launched stores included): a qualifying basket bought on its store page or a buy link ships as a letter, and the shopper is told before paying. A letter has no carrier tracking: its order events and tracking page state the expected window, and POST /v1/order/{id}/missing-letter reships it once if it does not arrive.
One of standard priority express letter
options[].labelstringrequired
options[].coststringrequired
Formatted, e.g. "$7.50". cost_cents is the number to compute with.
options[].cost_centsintegerrequired
Flat per PARCEL, not per item: these items ship once, and this is what the order path will charge for the same method.
options[].estimated_deliveryobjectrequired
An estimate: the producing facility's own production estimate plus this 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).
options[].estimated_delivery.earlieststring (date)required
A date, not a timestamp: YYYY-MM-DD in UTC, business days after today.
options[].estimated_delivery.lateststring (date)required
options[].estimated_delivery.ships_bystring (date)required
YYYY-MM-DD, UTC: the day an order placed now should leave the facility, when its production estimate ends.
options[].estimated_delivery.transit_daysstringrequired
Prose, e.g. "3-5 business days": the transit window after production.
options[].estimated_delivery.is_estimateboolean
Always true: these are estimates, never a promise.
Always true
options[].surchargesobject[]required
Compatibility itemisation of charges already inside cost_cents, never added to it. Current quotes contain no seasonal peak-postage surcharge: PrintedSimply absorbs the carrier expense, so this array is empty.
options[].surcharges[].codestringrequired
peak_season: the carrier's temporary holiday price change.
Always peak_season
options[].surcharges[].reasonstringrequired
What it is, in words.
options[].surcharges[].amount_centsintegerrequired
How much of the shipping figure this is, in cents, folded the way that figure is (all-in where the figure is all-in).
at least 1
options[].surcharges[].windowobjectrequired
The days it applies on, both inclusive.
options[].surcharges[].window.fromstring (date)required
YYYY-MM-DD, UTC.
options[].surcharges[].window.throughstring (date)required
YYYY-MM-DD, UTC.
options[].surcharges[].sourcestring (uri)required
Where the amount and the dates come from: the carrier's own announcement.
options[].surcharges[].included_instringrequired
Always shipping: the figure this is part of. Never an additional charge.
Always shipping
deliver_by_checkobject
The answer to deliver_by, read as an estimate: production and transit are the facility's and the carrier's estimates, so a day that meets can still be missed. Present only when deliver_by was sent and there is an estimate to judge it against.
deliver_by_check.requestedstring (date)required
The day asked about, as sent.
deliver_by_check.meetsbooleanrequired
On a quote: whether its own method's estimate ends on or before requested (estimated_delivery.latest, never the earliest day). On a shipping estimate: whether any parcel method listed does. False when a carrier advisory touches the destination (status is at_risk): true exactly when status is meets.
deliver_by_check.earliest_methodstring | anyrequired
The parcel method on offer whose estimate ends soonest, when it ends on or before requested; null when no method on offer is estimated to arrive by then. Never letter.
deliver_by_check.latest_order_daystring (date) | nullrequired
The last UTC day an order can be placed and still be estimated to arrive by requested, computed by the same estimate as estimated_delivery from the same facility: on a quote, for its own method; on a shipping estimate, for the parcel method listed that allows the latest day. Any time that day counts, and it may be a weekend or a holiday (an order placed then starts counting on the next operating day). Null exactly when no order placed today or later is estimated to arrive by requested, so it is null when status is misses. It reads the estimate alone, never a carrier advisory. An estimate, like the dates it reads.
deliver_by_check.statusstringrequired
The verdict. misses: the estimate ends after requested. at_risk: the estimate ends by then, but a carrier advisory (advisories) touches the destination while the parcel would be on its way. meets: the estimate ends by then and no advisory touches it.
One of meets at_risk misses
deliver_by_check.advisoriesobject[]required
The carrier advisories that touch the destination between today and the estimate's latest day; empty when none does.
deliver_by_check.advisories[].idstringrequired
adv_….
deliver_by_check.advisories[].carrierstringrequired
The carrier that posted it, as it names itself, e.g. "USPS".
deliver_by_check.advisories[].statesstring[]required
USPS state codes it touches. With zip_prefixes both empty, it touches every US destination.
deliver_by_check.advisories[].zip_prefixesstring[]required
ZIP prefixes (one to five digits) it touches, beside states.
deliver_by_check.advisories[].fromstring (date)required
The first day it applies, YYYY-MM-DD in UTC, inclusive.
deliver_by_check.advisories[].throughstring (date)required
The last day it applies, YYYY-MM-DD in UTC, inclusive.
deliver_by_check.advisories[].activebooleanrequired
Whether today (UTC) is inside from–through.
deliver_by_check.advisories[].extra_daysintegerrequired
The carrier's estimate of the business days it adds, as posted. An estimate.
deliver_by_check.advisories[].messagestringrequired
One sentence about it.
deliver_by_check.advisories[].sourcestringrequired
The carrier's own notice, as a URL.
delivery_riskobject
Present only when the lane carries a known risk worth stating before the order. Non-binding. When a carrier advisory touches the destination between today and the estimate's latest day, at_risk is true and advisories lists them; a quote may also carry its lane's lead-time read beside them.
delivery_risk.at_riskboolean
Present, and true, when advisories is.
Always true
delivery_risk.advisoriesobject[]
The carrier advisories that touch the destination while the parcel would be on its way.
The same fields as deliver_by_check.advisories

meta

pageinteger
totalinteger
limitinteger
The page size actually applied, which is not necessarily the one asked for — the operation's own ceiling wins.
pagesinteger
total over limit, rounded up.
next_cursorstring | null
On a cursor-paged operation: send this back as cursor for the next page. Null on the last page. Absent on operations that do not page by cursor.
has_moreboolean
On a list operation whose meta is ListMeta: whether another page follows this one.

Example response

{
  "status": "success",
  "data": {
    "destination": {
      "zip": "78701",
      "country": "US"
    },
    "total_items": 100,
    "shipping_class": {
      "name": "parcel_1lb",
      "weight_oz": 12.6
    },
    "options": [
      {
        "method": "standard",
        "label": "Standard Shipping",
        "cost": "$8.99",
        "cost_cents": 899,
        "estimated_delivery": {
          "earliest": "2026-10-20",
          "latest": "2026-10-26",
          "ships_by": "2026-10-14",
          "is_estimate": true,
          "transit_days": "4-8 business days"
        },
        "surcharges": []
      }
    ]
  },
  "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_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).
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_unavailable sku_not_available
destination_unavailable — the destination is outside the US, and this estimate prices our own plant's shipping, which goes to US addresses only. details.reason is destination_not_us and details.country names the destination. 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_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 Shipping operation

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 least 1 entry

items[].skustringrequired

non-empty

items[].product_idinteger

Catalog product ID

items[].quantityintegerrequired

at least 1

items[].sizestring

Product size (e.g. S, M, L, XL)

items[].colorstring

Product color

shipping_addressobject

Where the parcel goes. Only country decides the price (the rate depends on the method and the parcel's weight class, not the zone), so a country-only address is a complete request; zip is echoed back in destination when given. state and zip also decide which carrier advisories touch the destination (delivery_risk, deliver_by_check.status): a destination given by country alone is touched by every one. Required unless address_to is sent.

shipping_address.statestring

shipping_address.zipstring

Optional. Echoed back as destination.zip; null in the response when omitted.

non-empty

shipping_address.countrystring

Default US

address_toobject

The same destination under the name POST /order gives it, so the order's own address_to can be sent as it is: only state, zip and country are read, and the rest is ignored. Send this or shipping_address; both are accepted only when every field they both give agrees (the country defaults to US), and otherwise refused 400 validation_error.

address_to.statestring

address_to.zipstring

Optional. Echoed back as destination.zip; null in the response when omitted.

non-empty

address_to.countrystring

Default US

deliver_bystring (date)

A day the order should arrive by, YYYY-MM-DD (UTC). Answered in deliver_by_check, judged against the estimate's latest day rather than its earliest, from the facility's production estimate and the method's transit window. Optional; a day before today, or anything but a real date, is 400 validation_error.

Request

Try it

POST /api/v1/shipping/estimate

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

Response 200

Every method, priced per PARCEL rather than per item, with business-day windows.

data

destinationobjectrequired
Echoed, not priced from.
destination.zipstring | nullrequired
Null when the caller estimated by country alone.
destination.countrystringrequired
total_itemsintegerrequired
Units across the request. The cost is per parcel regardless.
shipping_classobject
The parcel these items pack into, which prices every parcel option: a weight band (parcel_1lb, parcel_2lb, parcel_5lb, parcel_over_5lb), with _tube when a poster or wall decal ships rolled. Estimated from the items' print area, not weighed.
shipping_class.namestringrequired
shipping_class.weight_oznumberrequired
Estimated shipped weight in ounces, packing tube included.
optionsobject[]required
options[].methodstringrequired
The shipping tiers this platform prices. Per parcel, not per item: standard by the parcel's weight class (POST /v1/shipping/estimate reports it), and for items made at the partner facility (apparel, mugs) at the larger of that and the partner's own estimate for the parcel; priority and express at their price and never below standard for the same parcel. An unrecognised value is refused with 400 validation_error rather than priced as standard. standard is always offered; priority and express are offered when priced (each at or above the USPS cost of the service), and until then a request for either is refused 400 shipping_method_unavailable, with details.offered naming the methods that are, and nothing is charged. letter is untracked letter mail for stickers and small vinyl decals from our own plant, offered only where the platform prices it, for an order whose every item qualifies, within a unit and an order-value ceiling: otherwise a request for it is refused 400 letter_mail_unavailable with details.reason, and nothing is charged. On the API it is never chosen for you — no default, estimate or storefront mapping picks it — and it is placed through POST /v1/order only (bulk and bundle orders ship by parcel). A hosted store is the one exception, and only where its merchant turned on small orders by letter in the dashboard's store editor (off by default, launched stores included): a qualifying basket bought on its store page or a buy link ships as a letter, and the shopper is told before paying. A letter has no carrier tracking: its order events and tracking page state the expected window, and POST /v1/order/{id}/missing-letter reships it once if it does not arrive.
One of standard priority express letter
options[].labelstringrequired
options[].coststringrequired
Formatted, e.g. "$7.50". cost_cents is the number to compute with.
options[].cost_centsintegerrequired
Flat per PARCEL, not per item: these items ship once, and this is what the order path will charge for the same method.
options[].estimated_deliveryobjectrequired
An estimate: the producing facility's own production estimate plus this 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).
options[].estimated_delivery.earlieststring (date)required
A date, not a timestamp: YYYY-MM-DD in UTC, business days after today.
options[].estimated_delivery.lateststring (date)required
options[].estimated_delivery.ships_bystring (date)required
YYYY-MM-DD, UTC: the day an order placed now should leave the facility, when its production estimate ends.
options[].estimated_delivery.transit_daysstringrequired
Prose, e.g. "3-5 business days": the transit window after production.
options[].estimated_delivery.is_estimateboolean
Always true: these are estimates, never a promise.
Always true
options[].surchargesobject[]required
Compatibility itemisation of charges already inside cost_cents, never added to it. Current quotes contain no seasonal peak-postage surcharge: PrintedSimply absorbs the carrier expense, so this array is empty.
options[].surcharges[].codestringrequired
peak_season: the carrier's temporary holiday price change.
Always peak_season
options[].surcharges[].reasonstringrequired
What it is, in words.
options[].surcharges[].amount_centsintegerrequired
How much of the shipping figure this is, in cents, folded the way that figure is (all-in where the figure is all-in).
at least 1
options[].surcharges[].windowobjectrequired
The days it applies on, both inclusive.
options[].surcharges[].window.fromstring (date)required
YYYY-MM-DD, UTC.
options[].surcharges[].window.throughstring (date)required
YYYY-MM-DD, UTC.
options[].surcharges[].sourcestring (uri)required
Where the amount and the dates come from: the carrier's own announcement.
options[].surcharges[].included_instringrequired
Always shipping: the figure this is part of. Never an additional charge.
Always shipping
deliver_by_checkobject
The answer to deliver_by, read as an estimate: production and transit are the facility's and the carrier's estimates, so a day that meets can still be missed. Present only when deliver_by was sent and there is an estimate to judge it against.
deliver_by_check.requestedstring (date)required
The day asked about, as sent.
deliver_by_check.meetsbooleanrequired
On a quote: whether its own method's estimate ends on or before requested (estimated_delivery.latest, never the earliest day). On a shipping estimate: whether any parcel method listed does. False when a carrier advisory touches the destination (status is at_risk): true exactly when status is meets.
deliver_by_check.earliest_methodstring | anyrequired
The parcel method on offer whose estimate ends soonest, when it ends on or before requested; null when no method on offer is estimated to arrive by then. Never letter.
deliver_by_check.latest_order_daystring (date) | nullrequired
The last UTC day an order can be placed and still be estimated to arrive by requested, computed by the same estimate as estimated_delivery from the same facility: on a quote, for its own method; on a shipping estimate, for the parcel method listed that allows the latest day. Any time that day counts, and it may be a weekend or a holiday (an order placed then starts counting on the next operating day). Null exactly when no order placed today or later is estimated to arrive by requested, so it is null when status is misses. It reads the estimate alone, never a carrier advisory. An estimate, like the dates it reads.
deliver_by_check.statusstringrequired
The verdict. misses: the estimate ends after requested. at_risk: the estimate ends by then, but a carrier advisory (advisories) touches the destination while the parcel would be on its way. meets: the estimate ends by then and no advisory touches it.
One of meets at_risk misses
deliver_by_check.advisoriesobject[]required
The carrier advisories that touch the destination between today and the estimate's latest day; empty when none does.
deliver_by_check.advisories[].idstringrequired
adv_….
deliver_by_check.advisories[].carrierstringrequired
The carrier that posted it, as it names itself, e.g. "USPS".
deliver_by_check.advisories[].statesstring[]required
USPS state codes it touches. With zip_prefixes both empty, it touches every US destination.
deliver_by_check.advisories[].zip_prefixesstring[]required
ZIP prefixes (one to five digits) it touches, beside states.
deliver_by_check.advisories[].fromstring (date)required
The first day it applies, YYYY-MM-DD in UTC, inclusive.
deliver_by_check.advisories[].throughstring (date)required
The last day it applies, YYYY-MM-DD in UTC, inclusive.
deliver_by_check.advisories[].activebooleanrequired
Whether today (UTC) is inside from–through.
deliver_by_check.advisories[].extra_daysintegerrequired
The carrier's estimate of the business days it adds, as posted. An estimate.
deliver_by_check.advisories[].messagestringrequired
One sentence about it.
deliver_by_check.advisories[].sourcestringrequired
The carrier's own notice, as a URL.
delivery_riskobject
Present only when the lane carries a known risk worth stating before the order. Non-binding. When a carrier advisory touches the destination between today and the estimate's latest day, at_risk is true and advisories lists them; a quote may also carry its lane's lead-time read beside them.
delivery_risk.at_riskboolean
Present, and true, when advisories is.
Always true
delivery_risk.advisoriesobject[]
The carrier advisories that touch the destination while the parcel would be on its way.
The same fields as deliver_by_check.advisories

meta

pageinteger
totalinteger
limitinteger
The page size actually applied, which is not necessarily the one asked for — the operation's own ceiling wins.
pagesinteger
total over limit, rounded up.
next_cursorstring | null
On a cursor-paged operation: send this back as cursor for the next page. Null on the last page. Absent on operations that do not page by cursor.
has_moreboolean
On a list operation whose meta is ListMeta: whether another page follows this one.

Example response

{
  "status": "success",
  "data": {
    "destination": {
      "zip": "78701",
      "country": "US"
    },
    "total_items": 100,
    "shipping_class": {
      "name": "parcel_1lb",
      "weight_oz": 12.6
    },
    "options": [
      {
        "method": "standard",
        "label": "Standard Shipping",
        "cost": "$8.99",
        "cost_cents": 899,
        "estimated_delivery": {
          "earliest": "2026-10-20",
          "latest": "2026-10-26",
          "ships_by": "2026-10-14",
          "is_estimate": true,
          "transit_days": "4-8 business days"
        },
        "surcharges": []
      }
    ]
  },
  "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_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).

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

destination_unavailable — the destination is outside the US, and this estimate prices our own plant's shipping, which goes to US addresses only. details.reason is destination_not_us and details.country names the destination. 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_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.

Estimate shipping costs

Parameters

Request body application/json, required

Request

Response 200

Errors

Estimate shipping costs

Parameters

Request body application/json, required

Request

Response 200

Errors

Response `200`

Response `200`