Remove item from order

DELETE/{id}/item/{itemId}/cancel

Remove an item from an order and refund its full cost.

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

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

DELETE /api/v1/{id}/item/{itemId}/cancel

curl -X DELETE "https://portal.printedsimply.com/api/v1/test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk/item/itm_fowT5-1iZwSnQcGX0ByoA64l/cancel" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Idempotency-Key: cancel-item-$(date +%s)"

Response `200`

Item removed and refunded

data

item_idstringrequired
test_modeboolean
True when the order is a sandbox order.
refundedstringrequired
refunded_centsintegerrequired

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": {
    "item_id": "itm_vNx36IWd8kx2dCQqkFbsTVg3",
    "refunded": "$0.00",
    "refunded_cents": 0,
    "test_mode": true
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

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).
404
Resource not found
409order_not_modifiable
order_not_modifiable — the order has gone into production (or later), past the point where items can be removed.
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.
500
Refund processing failed
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.
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.

Every Order Items operation

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

Try it

DELETE /api/v1/{id}/item/{itemId}/cancel

curl -X DELETE "https://portal.printedsimply.com/api/v1/test_ord_wVK9ZiG-VYiPrlSeBUBmrUVk/item/itm_fowT5-1iZwSnQcGX0ByoA64l/cancel" \
  -H "x-api-key: ps_test_YOUR_KEY" \
  -H "Idempotency-Key: cancel-item-$(date +%s)"

Response 200

Item removed and refunded

data

item_idstringrequired
test_modeboolean
True when the order is a sandbox order.
refundedstringrequired
refunded_centsintegerrequired

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": {
    "item_id": "itm_vNx36IWd8kx2dCQqkFbsTVg3",
    "refunded": "$0.00",
    "refunded_cents": 0,
    "test_mode": true
  },
  "request_id": "4e3753e1-48dd-4313-bfd8-48e4af4e116a"
}

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

404

Resource not found

409order_not_modifiable

order_not_modifiable — the order has gone into production (or later), past the point where items can be removed.

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.

500

Refund processing failed

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.

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.

Remove item from order

Parameters

Request

Response 200

Errors

Remove item from order

Parameters

Request

Response 200

Errors

Response `200`

Response `200`