Update item quantity

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.

• itemIdpath · stringrequired

  Item ID

• 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

• quantityintegerrequired

  1 to 10000

Request

curl -X PUT "https://portal.printedsimply.com/api/v1/test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk/item/itm_fowT5-1iZwSnQcGX0ByoA64l" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-item-$(date +%s)" \
  -d '{
    "quantity": 5
  }'

Response 200

{
  "status": "success",
  "data": {
    "item": {
      "id": "itm_vNx36IWd8kx2dCQqkFbsTVg3",
      "sku": "magnet-4x4",
      "previous_quantity": 25,
      "new_quantity": 5,
      "unit_price": "$2.47",
      "delta": "$-49.40"
    },
    "shipping": {
      "method": "standard",
      "shipping_class": {
        "name": "parcel_2lb",
        "weight_oz": 17.1
      },
      "delta_cents": -700,
      "shipping_cents": 1399
    },
    "total_delta_cents": -5640,
    "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_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_order

  order_not_modifiable — the order has gone into production (or later), past the point where its items can change. shopper_paid_order — a quantity increase on an order a shopper paid for (a drop, a checkout link or an agent checkout); it would be charged to your card and refunded to the shopper. A decrease is allowed and refunds the shopper's own charge.

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

  variable_data_invalid — the line was placed with per-unit variable data, which fixes its quantity to the units it carries (details.problems[0].code is count_mismatch). Nothing was charged or refunded; cancel the line and order it again with the units you want. artwork_required — a new quantity for a line with no artwork on record, on a live order at our own plant (details.item_id, details.sku): the change is sent to the plant with the line's SKU and its file, and the plant prints every line from a file, so it is refused before anything is charged or refunded. Cancel the line and add it again with a print_file. A test key is not refused, and a PUT that restates the current quantity sends the plant nothing. sku_not_available — a quantity increase on a line our own plant does not make (one placed before this portal sold only its own products); refused before anything is charged, and details.skus names it. A decrease is allowed.

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

• 500refund_failed

  refund_failed — the quantity decrease was applied but the refund for it could not be processed. The money is owed and support is alerted; do not retry, which would decrease the quantity again.

• 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 quantity changes are also refused before any charge or refund because the plant handler is not confirmed.

• 502

  Production system error

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