Printify

Printify

Print-on-demand platform. Two parallel domains: the global catalog (what you can make) and your shops (what you sell, fulfil, and ship).

Entity Hierarchy

Global Catalog (no shop_id needed)

• Blueprints — product templates (t-shirts, hoodies, mugs, posters, …). Hundreds of items; the list endpoint returns every one in a single response.
• Print Providers — manufacturing partners. Each has a location and a list of decoration_methods (dtg, embroidery, dtf, …).
• Blueprint × Print Provider — the combination that determines what you can actually produce. For each combination Printify exposes:
  • Variants — every (size, color, decoration) option, each with a numeric id and a placeholders array describing the printable positions on the garment (front, back, neck, left_sleeve, right_sleeve …) with width/height in pixels.
  • Shipping profiles — handling time and per-method, per-region cost.

Shop-Scoped (requires shop_id)

• Shops — connected stores (Shopify, Etsy, WooCommerce) or API-only shops with sales_channel = "disconnected". Always list shops first.
• Uploads — image library. Upload by URL or base64; archive to retire. Image ids feed into product print_areas.
• Products — your saved designs. Each product binds one blueprint + print provider, plus the chosen variants (with prices) and the print_areas placing uploaded images at named positions on each variant. Products are draft until published to a connected sales channel. List calls are heavy upstream — browse with default compact list output, count_only for totals, or product_id for one full product.
• Orders — external orders you submit (line items + shipping method + address) or orders the sales channel pushes through Printify. New orders start on-hold; you confirm them by sending to production. Cancellation is status-gated.
• Webhooks — per-shop event subscriptions (order:created, order:shipment:delivered, product:publish:started, …).

Workflows

• Build a product: list shops → pick blueprint → list print providers for that blueprint → pick provider → fetch variants (note variant ids and placeholder positions) → upload artwork → upsert product with variants and print_areas → review mockups → publish to sales channel. For unattended runs, printify_create_and_publish can create, optionally reprice from cost, and publish in one call.
• Place an external order: list shops → list products (or fetch one) → calculate shipping for the line item + address → create order with shipping_method → send to production. Cancel before send-to-production for the highest success rate.
• Track fulfilment: subscribe a webhook to order:shipment:created and order:shipment:delivered, or poll order reads filtered by status or UTC date window (printify_get_orders_in_range, printify_get_orders_by_month).
• Manage artwork: upload images, list uploads, archive obsolete ones.

Gotchas

• shop_id is required for products, orders, and webhooks when multiple shops exist. Pass the numeric id from printify_get_shops — never placeholders such as auto. When the account has exactly one shop, omit shop_id and the platform uses default_scope from printify_get_shops. For multiple shops, call printify_set_default_shop once, then omit shop_id on later calls.
• blueprint_id + print_provider_id together are required for variants and shipping endpoints — variants belong to a specific provider.
• Image upload by URL fails (HTTP 400 code 10300) when Printify's fetcher cannot reach the URL or the host blocks bots; fall back to base64 contents. Upstream 10300 with a support reference is a Printify-side failure — retry with different artwork or contact Printify support.
• Product titles on create/update accept Etsy-style pipe separators, apostrophes, and punctuation — the product API only rejects an empty title (code 8150). Code 61003 is a sales-channel publish rule (for example Etsy listing hygiene), not something upsert enforces; do not strip | or caps before the upstream call.
• Order and shipping line items with product_id must use ids from the same shop — product read or list products. Wrong or deleted product ids used to reach Printify as HTTP 404 on shipping quotes; calculate shipping and create order now pre-check shop products and variant ids before POST.
• Product create variant ids must come from the blueprint variants read for the same blueprint_id and print_provider_id you pass to upsert. Mixing ids from another blueprint or provider returns HTTP 400 code 8251; upsert pre-validates ids against the catalog before POST. Never reuse variant ids after changing blueprint_id or print_provider_id — always re-read variants for the new pair.
• Published or locked products return HTTP 400 code 8252 ("disabled for editing") on PUT — create a new product or fix state in Printify instead of retrying the same update.
• Image ids in print_areas must be upload library ids from the image upload tool — not URLs, {upload_id} templates, or invented strings. Product create expects placeholders[].images[].id (nested array). Order-style {front: upload_id} maps are coerced when variant ids can be taken from variants[]; placeholder shorthand {position, id} is also accepted. Create/update and ad-hoc order line items probe the upload library before write.
• Print provider listing by blueprint returns a structured not-found outcome when blueprint_id is invalid — list blueprints first instead of retrying.
• Never pass blueprint_id or print_provider_id from memory — copy numeric ids from the immediately prior list response. Stale blueprint ids (HTTP 404 on single-blueprint fetch) and wrong blueprint×provider pairs dominate agent failures.
• Product list without product_id can take up to ~60s on large shops upstream; use default compact list with small limit, count_only for totals, or product_id for one product instead of parallel limit=50 fan-out.
• url= image uploads must be public http(s) URLs; localhost and file:// fail before upstream (use file_url, local_path, or contents).
• Publish/unpublish are sales-channel-gated. API-only shops with sales_channel = "disconnected" return HTTP 400 code 8254 on publish; unpublishing a never-published product returns code 8100.
• Order cancel is status-gated — once production picks the order up, cancel returns HTTP 400 code 8501.
• Webhook deletion needs the host of the registered URL as a query parameter; Printify rejects the call without it.