Create a cart

Submit finished artwork, quantities and your success URL for validation.

POST /v1/carts

POST/v1/carts

Idempotency-Key is required: 1–200 visible ASCII characters (0x21–0x7E), with no spaces. For example, store-order-1042-rev1. Use one value per order revision; retry identical instructions with the same value. Keys are scoped to partner and test/live mode.

Field / limit	Description
items	Required array of 1–1000 items. The sum of all quantities must also be at most 1000.
items[].image_url	Required front-image HTTPS URL: an API-issued image_url after successful upload, or your existing public image URL.
items[].quantity	Required positive integer. Maximum 1000, subject to the cart-wide total.
items[].back_image_url	Optional back-image HTTPS URL. An item-specific back overrides the shared back. If both are omitted, TCGPlaytest supplies its default card back. Send the matching reverse face for double-sided cards.
items[].sha256 / back_sha256	Optional 64-character hexadecimal SHA-256 of exact front/back file bytes, case-insensitive. Omit or use null for server-computed hashes. A mismatch fails that item/side.
back_image_url / back_sha256	Optional shared back URL and hash. Used only for items without an item-specific back URL; an item-specific back uses its own back_sha256.
card_stock	Optional; only "standard" is supported, and is the default.
retail_amount_cents	Required only for Connect: whole-cart card-sale subtotal, USD cents (50–5000000), excluding shipping/tax. Must cover printing; fees reduce earnings.
settlement	Optional: "hosted" (default), "connect" or "prepaid". Connect requires onboarding and retail_amount_cents; it never spends printing credit. Prepaid requires a key matching the platform Stripe mode and an enabled credit account; once artwork is open, quote, reserve credit and submit an order through the prepaid endpoints. Prepaid carts never expose checkout_url.
external_ref	Optional string of at most 200 UTF-16 code units (200 ordinary characters); no format restriction. Omitted/empty input becomes null. Returned for your reference; does not enforce uniqueness or idempotency.
return_url	Optional HTTPS URL on the exact registered website origin (scheme, hostname and port). Omit to use the registered website URL. A different subdomain is a different origin.

Unknown request fields are rejected. Do not send certification, affiliate_code, artwork-library IDs or partner-terms fields. The server copies the authenticated partner's accepted terms version and timestamp onto each new cart.

Create cart request JSON

{
  "external_ref": "store-order-1042",
  "return_url": "https://shop.example/order-complete",
  "items": [
    {
      "image_url": "https://images.example/front.png",
      "back_image_url": "https://images.example/back.jpg",
      "quantity": 3
    }
  ]
}

Example response: HTTP 202 with Retry-After: 3. The example timestamps are illustrative; your actual expires_at is authoritative.

202 validating cart response

{
  "id": "cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "validating",
  "external_ref": "store-order-1042",
  "card_count": 3,
  "card_stock": "standard",
  "affiliate_code": null,
  "progress": {
    "done": 0,
    "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"
}

TCGPlaytest · Cardify LLC Partner terms Support