Add item to order

Parameters

• idpath · stringrequired

  The order's order_id, or its portal_order_id (ord_…): either resolves the same order. An id the order answered to before it was re-routed resolves too.

• 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

• skustringrequired

  non-empty

• quantityintegerrequired

  1 to 10000

• print_filestring (uri)

Request

curl -X POST "https://portal.printedsimply.com/api/v1/test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk/item" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: add-item-$(date +%s)" \
  -d '{
    "sku": "MAGNET-4X4",
    "quantity": 25,
    "print_file": "https://example.com/magnet-design.png"
  }'

Response 200

{
  "status": "success",
  "data": {
    "item": {
      "id": "itm_vNx36IWd8kx2dCQqkFbsTVg3",
      "sku": "magnet-4x4",
      "quantity": 25,
      "unit_price": "$2.47",
      "charged": "$61.75"
    },
    "shipping": {
      "method": "standard",
      "shipping_class": {
        "name": "parcel_5lb",
        "weight_oz": 35
      },
      "delta_cents": 1200,
      "shipping_cents": 2099
    },
    "total_delta_cents": 7375,
    "test_mode": true,
    "artwork_check": {
      "lines": [
        {
          "item_index": 0,
          "sku": "magnet-4x4",
          "status": "passed",
          "width_px": 1200,
          "height_px": 1200,
          "findings": [],
          "print_size_in": [
            4,
            4
          ],
          "effective_dpi": 300,
          "min_dpi": 300
        }
      ],
      "would_refuse": false
    }
  },
  "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).

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

• 404

  Resource not found

• 409order_not_modifiableshopper_paid_orderconcurrent_modification

  order_not_modifiable — the order has gone into production (or later), past the point where items can be added. shopper_paid_order — a shopper paid for this order (a drop, a checkout link or an agent checkout), so it takes no charge on your card: its refunds go back to the shopper. Place a separate order instead. concurrent_modification — another line was being added to this order and did not finish within a few seconds: add-items on one order are taken one at a time, so the 100-line limit holds, and nothing was charged. Retry in a moment.

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

• 422artwork_not_printableartwork_requiredsku_not_available

  artwork_not_printable — the order is made at our own plant and the added line's artwork (print_file) cannot be printed as it is (unreachable, not_an_image, low_resolution). Checked before the line is priced or the card is charged: nothing was charged and the Idempotency-Key is free for the corrected line. details.problems[] and details.artwork_check are shaped as on POST /order's 422. artwork_required — the order is made at our own plant and the added line has no print_file, so there is nothing to print; refused before anything is read or charged, with details.items[] as on POST /order's 422. A test key is never refused for artwork; its 200 carries artwork_check.would_refuse (and artwork_check.missing_artwork for a line with none). sku_not_available — the added line is a product our own plant does not make; refused before it is priced or charged, and details.skus names it.

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

• 501not_supported_by_provider

  not_supported_by_provider — the order was produced by an independent network shop, which does not accept amendments at all. Never retryable, unlike the 409. Live PrintedSimply add-item calls are also refused before any charge because the plant handler is not confirmed.

• 502

  Production system error

• 503provider_unavailablepricing_erroridempotency_unavailable

  provider_unavailable (details.reason: plant_unreachable, with Retry-After) — the order is made at our own plant and the plant gave no answer about the added SKU (the request did not reach it, timed out, or came back 5xx), which is about the plant and not the SKU: a definite answer that it does not carry the SKU is still the 400 pricing_error. Asked before the card is charged, so nothing was charged and the same Idempotency-Key may be retried. A test order is not refused: its line is priced $0 with pricing_degraded: pricing_unavailable, as on POST /order. 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.