Create multi-address order

POST/orders/multi-ship

Place an order whose items ship to several addresses. Give the full item list once, then a shipment per destination naming the item indices that go there — every item in exactly one shipment. Each shipment is placed as its own order through the same path POST /orders/bulk uses (priced, charged, routed, and tracked independently, with quote honoring, spend caps, fraud gating, and webhooks identical to a batch), and the response groups them under group_id with order_ids and one row per shipment: shipment_id, index, status, order_id, portal_order_id, tracking_url, charged, error, address, items. Partial success is a 200: a shipment the platform refuses fails its own row and charges nothing while the others proceed; on a live key that includes a shipment whose address cannot be right as written (POST /addresses/validate's check), whose error starts address_invalid:. A test key places real sandbox orders that run the time-compressed lifecycle; a live key charges and routes to production — the same code path in both modes. At most 50 shipments per call. Counts as one request, against your rate limit and in your usage.

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

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
1 to 100 entries
items[].skustringrequired
non-empty
items[].product_idinteger
Catalog product ID
at least 1
items[].quantityintegerrequired
1 to 10000
items[].sizestring
Product size (e.g. S, M, L, XL)
items[].colorstring
Product color
items[].design_namestring
Design/artwork name
items[].artwork_urlstring (uri)
URL to artwork file
items[].print_filestring
URL or asset ID (ast_*)
items[].notesstring
Item-level notes
items[].artworkobject
Optional: how this line's artwork was made, and who approved it and when. A declaration you state, stored on the line as sent (approved_by sanitized, approved_at in UTC), echoed on the order's reads (line_items[].artwork) and on its order.created webhook. It never changes the price, the routing or the artwork check, and a line without it is placed exactly as before. Strict: an unknown key is a 400 validation_error.
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.
shipmentsobject[]required
at least 1 entry
shipments[].addressobjectrequired
shipments[].address.namestringrequired
non-empty
shipments[].address.companystring
shipments[].address.address1stringrequired
non-empty
shipments[].address.address2string
shipments[].address.citystringrequired
non-empty
shipments[].address.statestringrequired
non-empty
shipments[].address.zipstringrequired
non-empty
shipments[].address.countrystringrequired
ISO 3166-1 alpha-2 country code
exactly 2 characters
shipments[].address.phonestring
shipments[].address.emailstring (email)
shipments[].item_indicesinteger[]required
Indices into the items array for this shipment
at least 1 entry

Request

Try it

POST /api/v1/orders/multi-ship

curl -X POST "https://portal.printedsimply.com/api/v1/orders/multi-ship" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-multi-ship-order-$(date +%s)" \
  -d '{
    "items": [
      {
        "sku": "sticker-die-cut-3x3",
        "quantity": 50,
        "artwork_url": "https://example.com/logo.png"
      },
      {
        "sku": "sticker-die-cut-3x3",
        "quantity": 50,
        "artwork_url": "https://example.com/logo.png"
      }
    ],
    "shipments": [
      {
        "address": {
          "name": "Jane Doe",
          "address1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "item_indices": [
          0
        ]
      },
      {
        "address": {
          "name": "Sam Lee",
          "address1": "420 Pine St",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101",
          "country": "US"
        },
        "item_indices": [
          1
        ]
      }
    ]
  }'

Response `200`

Multi-ship group placed — one row per shipment, partial success inside a 200. A shipment our plant gave no answer about fails alone, uncharged, with POST /v1/orders/bulk's error starting plant_unreachable:, and the 200 carries Retry-After.

data

group_idstringrequired
The group the per-shipment orders were placed under (msh_…)
order_idsstring[]required
The order ids of the shipments that succeeded
shipmentsobject[]required
shipments[].shipment_idstringrequired
shipments[].indexintegerrequired
Position of this shipment in the request's shipments array
shipments[].statusstringrequired
One of success error
shipments[].order_idstring | null
The order placed for this shipment, on success
shipments[].portal_order_idstring | null
shipments[].tracking_urlstring (uri) | null
shipments[].chargedstring | null
shipments[].errorstring | null
Why this shipment was refused, on error: POST /v1/orders/bulk's row error, so plant_unreachable: means our plant gave no answer about a SKU and nothing was charged for it.
shipments[].error_codestring | null
POST /v1/orders/bulk's row error_code: the code error starts with, the code POST /order answers the same refusal with. Null on success, and on an error whose error starts with no code.
One of address_invalid authentication_required destination_unavailable duplicate_reference fraud_review fulfillment_error invalid_quote order_error payment_failed plant_unreachable pricing_error production_reconciliation_required provider_cannot_produce provider_unavailable quote_mismatch reference_check_unavailable spend_cap_exceeded unknown_sku
shipments[].address_checkobject | any
POST /order's address_check for this shipment's address, warnings included. A live shipment with an error finding is refused (error_code: address_invalid) before anything is charged. Null only where the check did not run.
shipments[].address_check.validbooleanrequired
False when any finding is an error.
shipments[].address_check.checkedbooleanrequired
False for an address outside the US, which is passed through as written.
shipments[].address_check.normalizedobjectrequired
The address in USPS style: upper case, no punctuation, ZIP+4 hyphenated, the state as its code, a unit typed into address1 moved to address2. Name, company, phone and email are trimmed and otherwise as sent.
shipments[].address_check.normalized.namestring
shipments[].address_check.normalized.companystring
shipments[].address_check.normalized.address1stringrequired
shipments[].address_check.normalized.address2string
shipments[].address_check.normalized.citystringrequired
shipments[].address_check.normalized.statestringrequired
shipments[].address_check.normalized.zipstringrequired
shipments[].address_check.normalized.countrystringrequired
shipments[].address_check.normalized.phonestring
shipments[].address_check.normalized.emailstring
shipments[].address_check.findingsobject[]required
shipments[].address_check.findings[].codestringrequired
The delivery_point_* codes come from delivery-point verification, which only a live POST /order, POST /orders/bulk entry or PUT /order/{id}/address runs, on a US address the other checks pass, and only where the deployment has USPS verification configured: delivery_point_not_found (error) — USPS answered that no delivery point exists at the street address; delivery_point_incomplete (warning) — the building exists but its unit is missing or not confirmed, or more than one address matched; delivery_point_confirmed (info). When USPS cannot be reached the order proceeds without them.
One of zip_format state_unknown zip_state_mismatch zip_state_border zip_unassigned po_box military_state military address2_split not_checked delivery_point_not_found delivery_point_incomplete delivery_point_confirmed
shipments[].address_check.findings[].severitystringrequired
error: the address cannot be right as written, and a live order or quote is refused with 422 address_invalid. warning: worth a look, never refused. info: what normalization did, or that nothing was checked.
One of error warning info
shipments[].address_check.findings[].fieldstringrequired
One of address1 address2 city state zip country
shipments[].address_check.findings[].messagestringrequired
shipments[].estimated_deliveryobject | null
On success: when this shipment's order should arrive, as POST /order's estimated_delivery dates it. Null on a refused shipment and on a lane that is not one of our own facilities.
shipments[].estimated_delivery.earlieststring (date)required
YYYY-MM-DD, UTC: the soonest the order should arrive.
shipments[].estimated_delivery.lateststring (date)required
YYYY-MM-DD, UTC: the latest it should, before anything goes wrong.
shipments[].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.
shipments[].estimated_delivery.is_estimatebooleanrequired
Always true: say it as an estimate wherever it is shown.
Always true
shipments[].addressobjectrequired
shipments[].address.namestringrequired
non-empty
shipments[].address.companystring
shipments[].address.address1stringrequired
non-empty
shipments[].address.address2string
shipments[].address.citystringrequired
non-empty
shipments[].address.statestringrequired
non-empty
shipments[].address.zipstringrequired
non-empty
shipments[].address.countrystringrequired
ISO 3166-1 alpha-2 country code
exactly 2 characters
shipments[].address.phonestring
shipments[].address.emailstring (email)
shipments[].itemsobject[]required
The items that ship to this address
total_itemsintegerrequired
total_shipmentsintegerrequired
succeededintegerrequired
failedintegerrequired
test_modebooleanrequired

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": {
    "group_id": "msh_4uWll5So4Wdjsd0Duh7TQtBN",
    "order_ids": [
      "test_ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
      "test_ord__w1OSQwtOy5IVUF4Z7Zx0gyn"
    ],
    "shipments": [
      {
        "shipment_id": "shp_IBpsk1RQj3kzZYkcBgSLl2Zo",
        "index": 0,
        "status": "success",
        "order_id": "test_ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
        "portal_order_id": "ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
        "tracking_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfbTVNUUN4eXlyWWVXMDdXN1Q2RWh2WXc4IiwiZXhwIjoiMjAyNy0wMS0xM1QxNTowMDoxOS4wMDBaIn0.68435d27ec0cb6ce5420fe82993e831b58dadf2b86100d464195bf6c8489e93e",
        "charged": "$0.00",
        "error": null,
        "error_code": null,
        "address_check": {
          "valid": true,
          "checked": true,
          "normalized": {
            "name": "Jane Doe",
            "address1": "123 MAIN ST",
            "city": "AUSTIN",
            "state": "TX",
            "zip": "78701",
            "country": "US"
          },
          "findings": []
        },
        "estimated_delivery": {
          "earliest": "2026-10-23",
          "latest": "2026-10-29",
          "ships_by": "2026-10-19",
          "is_estimate": true
        },
        "address": {
          "name": "Jane Doe",
          "address1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "items": [
          {
            "sku": "sticker-die-cut-3x3",
            "artwork_url": "https://example.com/logo.png",
            "quantity": 50
          }
        ]
      },
      {
        "shipment_id": "shp_K44HhNfmUG5JUKJz2R9iXbbk",
        "index": 1,
        "status": "success",
        "order_id": "test_ord__w1OSQwtOy5IVUF4Z7Zx0gyn",
        "portal_order_id": "ord__w1OSQwtOy5IVUF4Z7Zx0gyn",
        "tracking_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfVzVWdDk4NTlUc3JvZWt1QkptRm5tYnAyIiwiZXhwIjoiMjAyNy0wMS0xM1QxNTowMDoxOS4wMDBaIn0.01b69cca187803b0988f73da9cfc9548469566673537466b5a1360a35fed516c",
        "charged": "$0.00",
        "error": null,
        "error_code": null,
        "address_check": {
          "valid": true,
          "checked": true,
          "normalized": {
            "name": "Sam Lee",
            "address1": "420 PINE ST",
            "city": "SEATTLE",
            "state": "WA",
            "zip": "98101",
            "country": "US"
          },
          "findings": []
        },
        "estimated_delivery": {
          "earliest": "2026-10-23",
          "latest": "2026-10-29",
          "ships_by": "2026-10-19",
          "is_estimate": true
        },
        "address": {
          "name": "Sam Lee",
          "address1": "420 Pine St",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101",
          "country": "US"
        },
        "items": [
          {
            "sku": "sticker-die-cut-3x3",
            "artwork_url": "https://example.com/logo.png",
            "quantity": 50
          }
        ]
      }
    ],
    "total_items": 2,
    "total_shipments": 2,
    "succeeded": 2,
    "failed": 0,
    "test_mode": true
  },
  "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).
402
Payment failed or no payment method configured
403sandbox_only
sandbox_only — the account is restricted to sandbox mode and the request used a live key. Every shipment is placed through POST /v1/orders/bulk, which refuses the whole batch before any shipment is placed, and that refusal is answered here unchanged.
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.
422variable_data_invalid variable_data_unavailable sku_not_available
variable_data_invalid or variable_data_unavailable — an item's variable_data was refused by POST /v1/orders/bulk, which answers before any shipment is placed or charged; the refusal is answered here unchanged, and each problem's order_index is the shipment's position in shipments. sku_not_available — an item is a product our own plant does not make; refused before any shipment is placed or charged, and details.skus names each one.
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.
502internal_error
internal_error — the placement answered without per-shipment results, so this response cannot say which shipments were placed. Check GET /v1/orders before retrying.
503idempotency_unavailable
idempotency_unavailable — the request carried an Idempotency-Key and the ledger that makes it mean at-most-once could not be reached, so nothing ran and nothing was charged; retry the same request with the same key after Retry-After.

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

1 to 100 entries

items[].skustringrequired

non-empty

items[].product_idinteger

Catalog product ID

at least 1

items[].quantityintegerrequired

1 to 10000

items[].sizestring

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

items[].colorstring

Product color

items[].design_namestring

Design/artwork name

items[].artwork_urlstring (uri)

URL to artwork file

items[].print_filestring

URL or asset ID (ast_*)

items[].notesstring

Item-level notes

items[].artworkobject

Optional: how this line's artwork was made, and who approved it and when. A declaration you state, stored on the line as sent (approved_by sanitized, approved_at in UTC), echoed on the order's reads (line_items[].artwork) and on its order.created webhook. It never changes the price, the routing or the artwork check, and a line without it is placed exactly as before. Strict: an unknown key is a 400 validation_error.

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.

shipmentsobject[]required

at least 1 entry

shipments[].addressobjectrequired

shipments[].address.namestringrequired

non-empty

shipments[].address.companystring

shipments[].address.address1stringrequired

non-empty

shipments[].address.address2string

shipments[].address.citystringrequired

non-empty

shipments[].address.statestringrequired

non-empty

shipments[].address.zipstringrequired

non-empty

shipments[].address.countrystringrequired

ISO 3166-1 alpha-2 country code

exactly 2 characters

shipments[].address.phonestring

shipments[].address.emailstring (email)

shipments[].item_indicesinteger[]required

Indices into the items array for this shipment

at least 1 entry

Request

Try it

POST /api/v1/orders/multi-ship

curl -X POST "https://portal.printedsimply.com/api/v1/orders/multi-ship" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-multi-ship-order-$(date +%s)" \
  -d '{
    "items": [
      {
        "sku": "sticker-die-cut-3x3",
        "quantity": 50,
        "artwork_url": "https://example.com/logo.png"
      },
      {
        "sku": "sticker-die-cut-3x3",
        "quantity": 50,
        "artwork_url": "https://example.com/logo.png"
      }
    ],
    "shipments": [
      {
        "address": {
          "name": "Jane Doe",
          "address1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "item_indices": [
          0
        ]
      },
      {
        "address": {
          "name": "Sam Lee",
          "address1": "420 Pine St",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101",
          "country": "US"
        },
        "item_indices": [
          1
        ]
      }
    ]
  }'

Response 200

data

group_idstringrequired
The group the per-shipment orders were placed under (msh_…)
order_idsstring[]required
The order ids of the shipments that succeeded
shipmentsobject[]required
shipments[].shipment_idstringrequired
shipments[].indexintegerrequired
Position of this shipment in the request's shipments array
shipments[].statusstringrequired
One of success error
shipments[].order_idstring | null
The order placed for this shipment, on success
shipments[].portal_order_idstring | null
shipments[].tracking_urlstring (uri) | null
shipments[].chargedstring | null
shipments[].errorstring | null
Why this shipment was refused, on error: POST /v1/orders/bulk's row error, so plant_unreachable: means our plant gave no answer about a SKU and nothing was charged for it.
shipments[].error_codestring | null
POST /v1/orders/bulk's row error_code: the code error starts with, the code POST /order answers the same refusal with. Null on success, and on an error whose error starts with no code.
One of address_invalid authentication_required destination_unavailable duplicate_reference fraud_review fulfillment_error invalid_quote order_error payment_failed plant_unreachable pricing_error production_reconciliation_required provider_cannot_produce provider_unavailable quote_mismatch reference_check_unavailable spend_cap_exceeded unknown_sku
shipments[].address_checkobject | any
POST /order's address_check for this shipment's address, warnings included. A live shipment with an error finding is refused (error_code: address_invalid) before anything is charged. Null only where the check did not run.
shipments[].address_check.validbooleanrequired
False when any finding is an error.
shipments[].address_check.checkedbooleanrequired
False for an address outside the US, which is passed through as written.
shipments[].address_check.normalizedobjectrequired
The address in USPS style: upper case, no punctuation, ZIP+4 hyphenated, the state as its code, a unit typed into address1 moved to address2. Name, company, phone and email are trimmed and otherwise as sent.
shipments[].address_check.normalized.namestring
shipments[].address_check.normalized.companystring
shipments[].address_check.normalized.address1stringrequired
shipments[].address_check.normalized.address2string
shipments[].address_check.normalized.citystringrequired
shipments[].address_check.normalized.statestringrequired
shipments[].address_check.normalized.zipstringrequired
shipments[].address_check.normalized.countrystringrequired
shipments[].address_check.normalized.phonestring
shipments[].address_check.normalized.emailstring
shipments[].address_check.findingsobject[]required
shipments[].address_check.findings[].codestringrequired
The delivery_point_* codes come from delivery-point verification, which only a live POST /order, POST /orders/bulk entry or PUT /order/{id}/address runs, on a US address the other checks pass, and only where the deployment has USPS verification configured: delivery_point_not_found (error) — USPS answered that no delivery point exists at the street address; delivery_point_incomplete (warning) — the building exists but its unit is missing or not confirmed, or more than one address matched; delivery_point_confirmed (info). When USPS cannot be reached the order proceeds without them.
One of zip_format state_unknown zip_state_mismatch zip_state_border zip_unassigned po_box military_state military address2_split not_checked delivery_point_not_found delivery_point_incomplete delivery_point_confirmed
shipments[].address_check.findings[].severitystringrequired
error: the address cannot be right as written, and a live order or quote is refused with 422 address_invalid. warning: worth a look, never refused. info: what normalization did, or that nothing was checked.
One of error warning info
shipments[].address_check.findings[].fieldstringrequired
One of address1 address2 city state zip country
shipments[].address_check.findings[].messagestringrequired
shipments[].estimated_deliveryobject | null
On success: when this shipment's order should arrive, as POST /order's estimated_delivery dates it. Null on a refused shipment and on a lane that is not one of our own facilities.
shipments[].estimated_delivery.earlieststring (date)required
YYYY-MM-DD, UTC: the soonest the order should arrive.
shipments[].estimated_delivery.lateststring (date)required
YYYY-MM-DD, UTC: the latest it should, before anything goes wrong.
shipments[].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.
shipments[].estimated_delivery.is_estimatebooleanrequired
Always true: say it as an estimate wherever it is shown.
Always true
shipments[].addressobjectrequired
shipments[].address.namestringrequired
non-empty
shipments[].address.companystring
shipments[].address.address1stringrequired
non-empty
shipments[].address.address2string
shipments[].address.citystringrequired
non-empty
shipments[].address.statestringrequired
non-empty
shipments[].address.zipstringrequired
non-empty
shipments[].address.countrystringrequired
ISO 3166-1 alpha-2 country code
exactly 2 characters
shipments[].address.phonestring
shipments[].address.emailstring (email)
shipments[].itemsobject[]required
The items that ship to this address
total_itemsintegerrequired
total_shipmentsintegerrequired
succeededintegerrequired
failedintegerrequired
test_modebooleanrequired

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": {
    "group_id": "msh_4uWll5So4Wdjsd0Duh7TQtBN",
    "order_ids": [
      "test_ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
      "test_ord__w1OSQwtOy5IVUF4Z7Zx0gyn"
    ],
    "shipments": [
      {
        "shipment_id": "shp_IBpsk1RQj3kzZYkcBgSLl2Zo",
        "index": 0,
        "status": "success",
        "order_id": "test_ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
        "portal_order_id": "ord_8zJ_6hfCTgPoJN4qw3R7zXKn",
        "tracking_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfbTVNUUN4eXlyWWVXMDdXN1Q2RWh2WXc4IiwiZXhwIjoiMjAyNy0wMS0xM1QxNTowMDoxOS4wMDBaIn0.68435d27ec0cb6ce5420fe82993e831b58dadf2b86100d464195bf6c8489e93e",
        "charged": "$0.00",
        "error": null,
        "error_code": null,
        "address_check": {
          "valid": true,
          "checked": true,
          "normalized": {
            "name": "Jane Doe",
            "address1": "123 MAIN ST",
            "city": "AUSTIN",
            "state": "TX",
            "zip": "78701",
            "country": "US"
          },
          "findings": []
        },
        "estimated_delivery": {
          "earliest": "2026-10-23",
          "latest": "2026-10-29",
          "ships_by": "2026-10-19",
          "is_estimate": true
        },
        "address": {
          "name": "Jane Doe",
          "address1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "items": [
          {
            "sku": "sticker-die-cut-3x3",
            "artwork_url": "https://example.com/logo.png",
            "quantity": 50
          }
        ]
      },
      {
        "shipment_id": "shp_K44HhNfmUG5JUKJz2R9iXbbk",
        "index": 1,
        "status": "success",
        "order_id": "test_ord__w1OSQwtOy5IVUF4Z7Zx0gyn",
        "portal_order_id": "ord__w1OSQwtOy5IVUF4Z7Zx0gyn",
        "tracking_url": "https://portal.printedsimply.com/track/eyJ2IjoxLCJ0IjoidHJhY2tpbmciLCJ0b2siOiJ0cmtfVzVWdDk4NTlUc3JvZWt1QkptRm5tYnAyIiwiZXhwIjoiMjAyNy0wMS0xM1QxNTowMDoxOS4wMDBaIn0.01b69cca187803b0988f73da9cfc9548469566673537466b5a1360a35fed516c",
        "charged": "$0.00",
        "error": null,
        "error_code": null,
        "address_check": {
          "valid": true,
          "checked": true,
          "normalized": {
            "name": "Sam Lee",
            "address1": "420 PINE ST",
            "city": "SEATTLE",
            "state": "WA",
            "zip": "98101",
            "country": "US"
          },
          "findings": []
        },
        "estimated_delivery": {
          "earliest": "2026-10-23",
          "latest": "2026-10-29",
          "ships_by": "2026-10-19",
          "is_estimate": true
        },
        "address": {
          "name": "Sam Lee",
          "address1": "420 Pine St",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101",
          "country": "US"
        },
        "items": [
          {
            "sku": "sticker-die-cut-3x3",
            "artwork_url": "https://example.com/logo.png",
            "quantity": 50
          }
        ]
      }
    ],
    "total_items": 2,
    "total_shipments": 2,
    "succeeded": 2,
    "failed": 0,
    "test_mode": true
  },
  "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).

402

Payment failed or no payment method configured

403sandbox_only

sandbox_only — the account is restricted to sandbox mode and the request used a live key. Every shipment is placed through POST /v1/orders/bulk, which refuses the whole batch before any shipment is placed, and that refusal is answered here unchanged.

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.

422variable_data_invalid variable_data_unavailable sku_not_available

variable_data_invalid or variable_data_unavailable — an item's variable_data was refused by POST /v1/orders/bulk, which answers before any shipment is placed or charged; the refusal is answered here unchanged, and each problem's order_index is the shipment's position in shipments. sku_not_available — an item is a product our own plant does not make; refused before any shipment is placed or charged, and details.skus names each one.

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.

502internal_error

internal_error — the placement answered without per-shipment results, so this response cannot say which shipments were placed. Check GET /v1/orders before retrying.

503idempotency_unavailable

idempotency_unavailable — the request carried an Idempotency-Key and the ledger that makes it mean at-most-once could not be reached, so nothing ran and nothing was charged; retry the same request with the same key after Retry-After.

Create multi-address order

Parameters

Request body application/json, required

Request

Response 200

Errors

Create multi-address order

Parameters

Request body application/json, required

Request

Response 200

Errors

Response `200`

Response `200`