printful-api
Use when working with Printful API v2 for product catalog, mockup generation, order management, file uploads, or webhooks. Also use when setting up Printful authentication or troubleshooting rate limits.
| Model | Source |
|---|---|
| inherit | pack: merch |
Overview
Section titled “Overview”Printful API v2 (Open Beta 2.0.0-beta) for print-on-demand — browse the catalog, generate mockups, upload print files, create orders, and receive fulfillment events via webhooks. Orders follow a draft-first model: create draft, then confirm separately. Mockup generation is async: POST a task, then poll or receive a webhook when complete.
Full Reference
┏━ 🔧 printful-api ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Printful API v2 reference — catalog to shipping ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Printful API
Section titled “Printful API”Overview
Section titled “Overview”Printful API v2 (Open Beta 2.0.0-beta) for print-on-demand — browse the catalog, generate mockups, upload print files, create orders, and receive fulfillment events via webhooks. Orders follow a draft-first model: create draft, then confirm separately. Mockup generation is async: POST a task, then poll or receive a webhook when complete.
Quick Reference
Section titled “Quick Reference”| Item | Value |
|---|---|
| API Version | v2 (Open Beta 2.0.0-beta) |
| Base URL | https://api.printful.com/v2/ |
| Auth | Bearer token (private) or OAuth2 (public apps) |
| Rate Limit | 120 req/min (leaky bucket), lower for mockups |
| File Max | 200 MB, 20k x 20k px, PNG/JPG |
| DPI | 150 (apparel), 300 (accessories/stickers) |
| Error Format | RFC 9457 (application/problem+json) |
| Mockups | Async: POST task → poll or webhook |
| Orders | Draft-first → confirm separately |
| Cost | API free. Pay product base + fulfillment per order |
| Docs | developers.printful.com/docs/v2-beta |
Reference Index
Section titled “Reference Index”| File | Contents |
|---|---|
reference/auth.md | Private tokens, OAuth2 flow, all scopes, multi-store header, localization |
reference/catalog.md | Catalog endpoints, sync products, pagination, product vs variant concepts |
reference/mockups.md | Async mockup tasks, polling, webhook, placements, batch pattern |
reference/orders.md | Order lifecycle, all endpoints, payload examples, shipping/tracking |
reference/files.md | File upload, file types, DPI/size specs, per-product printfile specs |
reference/webhooks.md | All 17 events, registration, HMAC-SHA256 verification, reliability pattern |
reference/rate-limits.md | Leaky bucket algorithm, limits table, response headers, backoff pattern |
reference/errors.md | RFC 9457 Problem Details format, HTTP status codes, validation errors |
Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.