{"openapi":"3.0.3","info":{"title":"The Agents Gift Shop — custom merch for agents (x402)","version":"1.0.0","description":"Pay-per-call print-on-demand store for autonomous agents. Describe a design, get AI artwork + product mockups, order it printed and shipped anywhere Printify ships. Paid endpoints return HTTP 402 with an x402 v2 challenge; pay in USDC on Base with any x402-aware client. No accounts: capability keys authorise follow-up calls.","x-guidance":"Start with GET /v1/meta or /llms.txt. Create a design with POST /v1/designs (paid), poll GET /v1/designs/{id} until status=ready, pick a variant from /variants, quote with POST /v1/orders/quote (free), pay with POST /v1/orders/{id}/pay (exactly the quoted total), then poll GET /v1/orders/{id} for tracking. Keep the design_key / order_key you are given.","contact":{"email":"support@theagentsgiftshop.com"}},"servers":[{"url":"https://theagentsgiftshop.com"}],"paths":{"/":{"get":{"summary":"Agent-first landing page","description":"Human/agent readable overview with the contract inline.","operationId":"get_","tags":["discovery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/llms.txt":{"get":{"summary":"Plain-text agent guide","description":"Everything an agent needs in one text file.","operationId":"get_llms_txt","tags":["discovery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/health":{"get":{"summary":"Liveness probe","description":"Returns ok plus payment-edge status.","operationId":"get_health","tags":["discovery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"x402":true,"network":"eip155:8453","schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/v1/meta":{"get":{"summary":"The machine contract","description":"Protocol, pricing, identity model and every endpoint with schemas.","operationId":"get_v1_meta","tags":["discovery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/openapi.json":{"get":{"summary":"OpenAPI 3 document","description":"Discovery document with x-payment-info for x402scan / Bazaar.","operationId":"get_openapi_json","tags":["discovery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/v1/catalog/products":{"get":{"summary":"Product line with retail prices and options","description":"Every product type you can put a design on: retail price (cents), sizes, colours, phone models, puzzle piece counts, print area, premium flag.","operationId":"get_v1_catalog_products","tags":["catalog"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"products":[{"product_type":"shirts","name":"T-Shirt","price_cents":2500,"sizes":["S","M"],"colors":["White"]}],"schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/v1/catalog/designs":{"get":{"summary":"Public design gallery","description":"Designs other agents made public. Any of them can be ordered. Paginated.","operationId":"get_v1_catalog_designs","tags":["catalog"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":""},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":""},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","popular"],"default":"newest"},"description":""},{"name":"product_type","in":"query","required":false,"schema":{"type":"string","enum":["shirts","sweaters","stickers","tote bags","long sleeve","mugs","puzzles","hats","phone cases","blankets"]},"description":""},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":80,"description":"substring match on title / niche"},"description":"substring match on title / niche"}],"security":[]}},"/v1/shipping/countries":{"get":{"summary":"Supported destination countries","description":"ISO-3166 alpha-2 codes accepted in shipping addresses.","operationId":"get_v1_shipping_countries","tags":["catalog"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"countries":{"US":"United States","CA":"Canada"},"schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"security":[]}},"/v1/designs/{id}":{"get":{"summary":"One design (status, images, title)","description":"Public designs need no key. Private designs require X-Design-Key. While generating, `status` is `generating` and `step` shows progress; poll every 5–10 s.","operationId":"get_v1_designs_id","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","status":"ready","step":"done","product_type":"shirts","title":"…","price_cents":2500,"images":{"artwork":"https://…png","mockup":"https://…png","lifestyle":"https://…png"},"orderable":true,"schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"}],"security":[]},"patch":{"summary":"Make a design public or private","description":"Public designs appear in the gallery and can be ordered by anyone.","operationId":"patch_v1_designs_id","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_public":{"type":"boolean"}},"required":["is_public"],"additionalProperties":false},"example":{"is_public":true}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]},"delete":{"summary":"Delete a design","description":"Removes the design, its images and its print product. Orders already placed are unaffected.","operationId":"delete_v1_designs_id","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]}},"/v1/designs/{id}/variants":{"get":{"summary":"Orderable variants for a design","description":"Printify variant ids with size / colour / model for the design's product. Pass `variant_id` in an order line item.","operationId":"get_v1_designs_id_variants","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","product_type":"shirts","variants":[{"variant_id":12345,"size":"M","color":"Black","title":"Black / M"}],"schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"}],"security":[]}},"/v1/designs":{"post":{"summary":"Create a design from a text brief (paid)","description":"Starts generation: artwork → product mockup → title/description → print-provider product → lifestyle photo. Settles before the job starts and returns 202 with design_id + design_key. Poll GET /v1/designs/{id} until status=ready (1–3 min).","operationId":"post_v1_designs","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","design_key":"dk_…(shown once; send as X-Design-Key)","status":"queued","product_type":"shirts","price_cents":2500,"poll":"/v1/designs/5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brief":{"type":"string","minLength":3,"maxLength":2000,"description":"What to draw. Put any words you want printed in quotes, e.g. a cat in sunglasses with 'Cool Cat' text"},"product_type":{"type":"string","enum":["shirts","sweaters","stickers","tote bags","long sleeve","mugs","puzzles","hats","phone cases","blankets"],"description":"One of the catalog product types (GET /v1/catalog/products). Premium types add $1.00."},"ai_assisted":{"type":"boolean","default":true,"description":"Let GPT expand the brief into a structured design spec (style, palette, text). false = your words verbatim"},"back_print":{"type":"boolean","default":false,"description":"Apparel only: also generate a back design (+$1.00, retail +$5)"},"is_public":{"type":"boolean","default":false,"description":"List the finished design in the public gallery"}},"required":["brief"],"additionalProperties":false},"example":{"brief":"A retro cat wearing sunglasses with 'Cool Cat' text","product_type":"shirts","ai_assisted":true,"back_print":false,"is_public":true}}}},"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"2.0000","max":"4.0000"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/designs/from-image":{"post":{"summary":"Create a design from your image (paid)","description":"Your image is restyled into print-ready artwork, mocked up, titled and turned into a product. Same polling flow as /v1/designs.","operationId":"post_v1_designs_from_image","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","design_key":"dk_…(shown once; send as X-Design-Key)","status":"queued","product_type":"shirts","price_cents":2500,"poll":"/v1/designs/5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","format":"uri","description":"Public https URL of a PNG/JPEG/WEBP (≤10 MB, 100–10000 px)"},"image_base64":{"type":"string","description":"Alternative to image_url: base64 (or data: URI) of the image"},"style":{"type":"string","maxLength":300,"description":"Optional style keywords for the restyle, e.g. 'watercolor, pastel'"},"product_type":{"type":"string","enum":["shirts","sweaters","stickers","tote bags","long sleeve","mugs","puzzles","hats","phone cases","blankets"],"description":"One of the catalog product types (GET /v1/catalog/products). Premium types add $1.00."},"is_public":{"type":"boolean","default":false}},"additionalProperties":false},"example":{"image_url":"https://example.com/my-logo.png","style":"bold vector","product_type":"mugs"}}}},"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"2.0000","max":"3.0000"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/designs/{id}/regenerate-text":{"post":{"summary":"New title + description preview (paid)","description":"Regenerates the SEO title and description. Apply with /apply or ignore.","operationId":"post_v1_designs_id_regenerate_text","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","preview":{"title":"…","description":"…","artwork":"https://…","mockup":"https://…"},"apply":"POST /v1/designs/{id}/apply","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.4"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"authorization"}}},"/v1/designs/{id}/regenerate-photo":{"post":{"summary":"New artwork + mockup preview (paid)","description":"Regenerates the artwork (optionally from a new brief) and its product mockup. Apply with /apply.","operationId":"post_v1_designs_id_regenerate_photo","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","preview":{"title":"…","description":"…","artwork":"https://…","mockup":"https://…"},"apply":"POST /v1/designs/{id}/apply","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2000,"description":"Optional new brief; defaults to the original"}},"additionalProperties":false},"example":{"prompt":"same idea but in a watercolor style"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.6"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/designs/{id}/regenerate-full":{"post":{"summary":"New artwork + text + lifestyle photo preview (paid)","description":"Everything regenerated at once. Apply with /apply.","operationId":"post_v1_designs_id_regenerate_full","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","preview":{"title":"…","description":"…","artwork":"https://…","mockup":"https://…"},"apply":"POST /v1/designs/{id}/apply","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2000,"description":"Optional new brief; defaults to the original"}},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/designs/{id}/mockup":{"post":{"summary":"Lifestyle mockup photo (paid)","description":"A photorealistic scene of a person using the product. Replaces the current lifestyle image.","operationId":"post_v1_designs_id_mockup","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","lifestyle":"https://…png","schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.6"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/designs/{id}/apply":{"post":{"summary":"Apply the last regeneration preview","description":"Copies the pending preview onto the design. If the artwork changed, the print product is rebuilt (status briefly `updating`).","operationId":"post_v1_designs_id_apply","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string","enum":["title","description","artwork","lifestyle"]},"description":"Subset to apply; default all"}},"additionalProperties":false},"example":{"fields":["title","artwork"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]}},"/v1/designs/{id}/retry":{"post":{"summary":"Re-run a failed generation (free)","description":"Allowed while the design is `failed`, up to 2 times, or when a report granted a retry.","operationId":"post_v1_designs_id_retry","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]}},"/v1/designs/{id}/report":{"post":{"summary":"Report a bad image","description":"Flags the design for operator review (wrong text, broken artwork, policy issue). A review may grant a free regeneration.","operationId":"post_v1_designs_id_report","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false},"example":{"reason":"The text is misspelled"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"},{"name":"X-Design-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]}},"/v1/me/designs":{"get":{"summary":"Designs created by the paying wallet (paid)","description":"Identity is the wallet that pays; lists every design it created, newest first. Keys are not re-shown.","operationId":"get_v1_me_designs","tags":["designs"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"design_id":"5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","design_key":"dk_…(shown once; send as X-Design-Key)","status":"queued","product_type":"shirts","price_cents":2500,"poll":"/v1/designs/5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","schema":"tags_v1"}],"total":1,"schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":""},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":""}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"authorization"}}},"/v1/designs/{id}/like":{"post":{"summary":"Like / unlike a public design (paid)","description":"Toggles a like from the paying wallet; drives the gallery's `popular` sort.","operationId":"post_v1_designs_id_like","tags":["gallery"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"design_id":"…","liked":true,"likes":3,"schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"design id"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"authorization"}}},"/v1/orders/quote":{"post":{"summary":"Quote an order (free)","description":"Validates the address and items, resolves print variants, prices real standard shipping and returns an order in `quoted` state with its total and an order_key. Quotes expire after 30 minutes. Nothing is charged here.","operationId":"post_v1_orders_quote","tags":["orders"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"order_id":"…","order_key":"ok_…(shown once; send as X-Order-Key)","status":"quoted","subtotal_cents":2500,"shipping_cents":499,"total_cents":2999,"total":"$29.99","quote_expires_at":1760600000.0,"pay":"POST /v1/orders/{id}/pay","schema":"tags_v1"}}}},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","properties":{"design_id":{"type":"string","format":"uuid"},"variant_id":{"type":"integer","description":"A variant_id from GET /v1/designs/{id}/variants (preferred)"},"size":{"type":"string","enum":["S","M","L","XL","2XL"],"description":"Apparel only, if variant_id is omitted"},"color":{"type":"string","description":"Apparel colour name from the variants list, if variant_id is omitted"},"phone_model":{"type":"string","description":"Phone cases only: a key from /v1/catalog/products options.phone_model"},"pieces":{"type":"string","enum":["96","252","500","1000"],"description":"Puzzles only"},"quantity":{"type":"integer","minimum":1,"maximum":99,"default":1},"design_key":{"type":"string","description":"Required only for your own private designs"}},"required":["design_id"],"additionalProperties":false}},"shipping_address":{"type":"object","description":"Printify-shaped shipping address. Use ISO-3166 alpha-2 country codes and the state/province code for region.","properties":{"first_name":{"type":"string","minLength":1,"maxLength":60},"last_name":{"type":"string","minLength":1,"maxLength":60},"email":{"type":"string","format":"email","description":"Order confirmation + shipping notifications go here"},"phone":{"type":"string","maxLength":32},"address1":{"type":"string","minLength":3,"maxLength":120},"address2":{"type":"string","maxLength":120},"city":{"type":"string","minLength":1,"maxLength":80},"region":{"type":"string","minLength":1,"maxLength":60,"description":"State / province code, e.g. CA"},"zip":{"type":"string","minLength":2,"maxLength":20},"country":{"type":"string","pattern":"^[A-Z]{2}$","enum":["US","CA","GB","AU","DE","FR","IE","NL","ES","IT"]}},"required":["first_name","last_name","email","address1","city","region","zip","country"],"additionalProperties":false}},"required":["items","shipping_address"],"additionalProperties":false},"example":{"items":[{"design_id":"5d1d7a2e-5c8f-4c3a-9f0e-2c3d4e5f6a7b","size":"M","color":"Black","quantity":1}],"shipping_address":{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","phone":"+1 415 555 0100","address1":"123 Computing Lane","address2":"","city":"San Francisco","region":"CA","zip":"94105","country":"US"}}}}},"security":[]}},"/v1/orders/{id}/pay":{"post":{"summary":"Pay a quoted order (paid, exactly the quoted total)","description":"The 402 challenge carries the quote total. On settlement the order is placed with the print provider and sent to production. Requires X-Order-Key.","operationId":"post_v1_orders_id_pay","tags":["orders"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"order_id":"…","status":"paid","total_cents":2999,"items":[{"design_id":"…","variant":"Black / M","quantity":1}],"tracking":{"number":"9400…","url":"https://…","carrier":"usps"},"schema":"tags_v1"}}}},"402":{"description":"Payment Required — x402 v2 challenge in the PAYMENT-REQUIRED header (base64 JSON); a v1-style JSON body is also included for legacy clients."},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"order id from /quote"},{"name":"X-Order-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"5.00","max":"5000.00"},"protocols":[{"x402":{}}],"asset":"USDC","network":"eip155:8453","payTo":"0xB0397dB76AAe8E292a6c6fC09F9B484b80158BcF","settlement":"upfront"}}},"/v1/orders/{id}":{"get":{"summary":"Order status and tracking","description":"Status flow: quoted → paid → in_production → shipped (tracking) → delivered. Requires X-Order-Key.","operationId":"get_v1_orders_id","tags":["orders"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"order_id":"…","status":"in_production","total_cents":2999,"items":[{"design_id":"…","variant":"Black / M","quantity":1}],"tracking":{"number":"9400…","url":"https://…","carrier":"usps"},"schema":"tags_v1"}}}},"401":{"description":"Missing or wrong capability key"},"429":{"description":"Rate limited (Retry-After header)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"order id"},{"name":"X-Order-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Capability key returned when the resource was created"}],"security":[]}}},"components":{"securitySchemes":{"x402":{"type":"http","scheme":"x402","description":"HTTP 402 Payment Required via x402 (USDC on Base)."}}}}