Retrieve a cart

Read validation progress, quality warnings and checkout availability.

GET /v1/carts/{id}

GET/v1/carts/{id}

Use the exact id returned by POST. Successful reads return HTTP 200 and Retry-After: 3, including when the cart has failed validation. POST and GET use the same cart response shape.

Field / limit	Description
id	Opaque cart ID. Keep it to poll and associate the cart with your customer/order.
status	validating, open, failed, converted, expired, blocked or cancelled; handling is listed below.
external_ref	Your reference string, or null.
card_count / card_stock	Integer sum of item quantities; stock is "standard".
affiliate_code	Saved affiliate-code string copied at creation for hosted checkout, or null. Prepaid carts use null and do not earn an affiliate commission. Read-only; existing carts keep their original setting.
progress.done / progress.total	Integers: completed unique-URL checks (including failures) / all unique URLs in this cart.
warnings	Advisory array of {item_index, side, code, message, width, height, recommended_width, recommended_height}. image_low_resolution does not fail a cart. Show the warning before ordering; hosted checkout also asks the customer to acknowledge it.
errors	Array of {item_index, side, code, message}. item_index is zero-based; side is front or back. Empty when no errors have been recorded.
partner_terms_version	Partner terms version saved by the server, or null for older carts without that record.
mode	test or live.
settlement	Present as "prepaid" or "connect" for those carts. Omitted for hosted checkout.
retail_amount_cents	Whole-cart card-sale subtotal in USD cents. Required only for Connect requests and returned for Connect carts. Shipping and tax are added separately.
checkout_url	Present only for an open hosted-checkout cart. Always omitted for prepaid carts and other statuses, not null. Use a returned URL verbatim.
order_id	Manufacturing order ID after payment is recorded; otherwise null. Use this for GET /v1/orders/{id}.
created_at / expires_at	RFC 3339 timestamp strings with timezone, for example 2026-10-06T12:00:00.000Z. UTC may also be represented by +00:00; fractional seconds can vary.

validating: continue polling. Errors can appear as checks finish; wait for the terminal result to get every bad item/side.
open: checks passed. For hosted checkout, open the cart with TCGPlaytest.checkout(cart) on your page; test mode opens the simulated checkout flow. For settlement: prepaid, continue with quote → reserve → submit on your server.
failed: stop polling, inspect all errors, fix the inputs and create a new cart with a new Idempotency-Key. Keep your existing API key.
converted: hosted payment, or both printing credit and customer shipping/tax payment, funded the order. An order ID is available; use order status/webhooks. For prepaid orders this does not verify the shopper's separate card purchase in your store.
expired, blocked, cancelled: checkout is unavailable. Stop polling; do not retry blocked content. An expired cart needs a new cart and idempotency key.

Example open response (test mode):

Open cart response

{
  "id": "cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "open",
  "external_ref": "store-order-1042",
  "card_count": 3,
  "card_stock": "standard",
  "affiliate_code": null,
  "progress": {
    "done": 2,
    "total": 2
  },
  "errors": [],
  "warnings": [],
  "partner_terms_version": "2026-10-04-partner-v2",
  "mode": "test",
  "order_id": null,
  "expires_at": "2026-10-13T12:00:00.000Z",
  "created_at": "2026-10-06T12:00:00.000Z",
  "checkout_url": "https://partner.tcgplaytest.com/partner-checkout/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}

Example failed response with two errors for the same item:

Failed cart response

{
  "id": "cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "external_ref": "store-order-1042",
  "card_count": 3,
  "card_stock": "standard",
  "affiliate_code": null,
  "progress": {
    "done": 2,
    "total": 2
  },
  "errors": [
    {
      "item_index": 0,
      "side": "front",
      "code": "image_invalid",
      "message": "Image is not a readable PNG or JPEG."
    },
    {
      "item_index": 0,
      "side": "back",
      "code": "image_unreachable",
      "message": "Image could not be downloaded."
    }
  ],
  "warnings": [],
  "partner_terms_version": "2026-10-04-partner-v2",
  "mode": "test",
  "order_id": null,
  "expires_at": "2026-10-13T12:00:00.000Z",
  "created_at": "2026-10-06T12:00:00.000Z"
}

TCGPlaytest · Cardify LLC Partner terms Support