printify-api

name	printify-api
description	Manages Printify print-on-demand operations via the Printify Public API (V1 + V2 Catalog). Supports shops, catalog exploration, products, orders, events, webhooks, and rate-limit-aware workflows using OAuth 2.0 or Personal Access Tokens.
metadata	{"short-description":"Printify shop, catalog, products, orders, webhooks","documentation":["https://developers.printify.com/","https://printify.com/API-terms/"]}
allowed-tools	["code_execution"]

Printify API Skill

What this skill does

Use this skill when you need to interact with a Printify merchant account or multiple merchant accounts (platform scenario). It focuses on:

• Shops: enumerate stores connected to an account
• Catalog (V1) and Catalog V2: blueprints, print providers, variants, shipping
• Products: list products; build and update product payloads; handle publish lifecycle
• Orders: list orders; build order submission payloads; filter by status or SKU
• Events and Webhooks: subscribe to webhook topics; verify webhook signatures
• Operational constraints: rate limits, retry/backoff behavior, error budget awareness

When to use V1 vs V2

• V1 (https://api.printify.com/v1/) is the primary API surface for shops/products/orders/uploads/events/webhooks.
• V2 (https://api.printify.com/v2/) is organized around the JSON:API specification and currently adds catalog shipping endpoints (including Economy Shipping costs).

Authentication models

Personal Access Token (single merchant)

• Best for automations that operate on a single Printify account.
• Token is created in Printify UI under profile connections and is valid for one year.
• Requests authenticate with: Authorization: Bearer <token>
• You must also send a User-Agent header.

Environment variables used by helper scripts:

• PRINTIFY_API_TOKEN (required for PAT)
• PRINTIFY_USER_AGENT (required)

OAuth 2.0 (platform / multi-merchant)

Use OAuth if your application connects multiple merchants.

Files:

• scripts/oauth.py (build authorize URL, exchange code for tokens, refresh token)

Environment variables:

• PRINTIFY_APP_ID
• PRINTIFY_OAUTH_ACCEPT_URL
• PRINTIFY_OAUTH_DECLINE_URL

Notes:

• Access tokens expire after ~6 hours; refresh tokens are required for long-lived access.
• Production accept/decline URLs must use HTTPS and a domain name (IP addresses are not supported).

Rate limits and operational constraints

This skill is explicitly rate-limit-aware.

Documented limits (per integration per account, not per token):

• Global: 600 requests/minute
• Catalog endpoints: additional 100 requests/minute
• Product publishing: 200 requests per 30 minutes
• Error responses should not exceed 5% of total requests

Files:

• scripts/rate_limit.py implements coarse client-side throttling.
• scripts/printify_client.py implements retry/backoff and 429 handling.

Webhooks

Use webhooks to reduce polling and minimize API calls.

Key behavior:

• Printify POSTs a JSON payload to your URL for the subscribed topic.
• Expected response: 200 OK
• If your endpoint returns a 4xx/5xx, Printify retries up to 3 times, then blocks the webhook for 1 hour.

Security:

• Use the webhook secret field when creating the webhook.
• Printify sends signature header: X-Pfy-Signature: sha256=<digest>
• Verify signature by computing HMAC-SHA256 over the raw request body bytes with your shared secret.

Files:

• scripts/webhooks.py (signature computation + constant-time comparison)
• examples/verify_webhook_signature_flask.py (reference integration)

Environment variables:

• PRINTIFY_WEBHOOK_SECRET

API navigation helpers

Because Printify publishes an OpenAPI spec and a Postman collection, this skill includes a script to fetch them:

• scripts/openapi/fetch_openapi.py

It stores artifacts in:

• references/openapi/
• references/postman/

Then you can generate a tag-grouped endpoints index:

• scripts/openapi/generate_reference_from_openapi.py

Minimal endpoint index (verified from docs)

Shops:

• GET /v1/shops.json

Products:

• GET /v1/shops/{shop_id}/products.json (supports limit and page)

Orders:

• GET /v1/shops/{shop_id}/orders.json (supports page, status, sku)

Webhooks:

• GET /v1/shops/{shop_id}/webhooks.json
• POST /v1/shops/{shop_id}/webhooks.json
• PUT /v1/shops/{shop_id}/webhooks/{webhook_id}.json
• DELETE /v1/shops/{shop_id}/webhooks/{webhook_id}.json?host={webhook_host}

Catalog V2 shipping:

• GET /v2/catalog/blueprints/{blueprint_id}/print_providers/{print_provider_id}/shipping.json
• GET /v2/catalog/blueprints/{blueprint_id}/print_providers/{print_provider_id}/shipping/{method}.json

Examples

• examples/list_shops.py
• examples/list_products.py
• examples/list_orders.py
• examples/create_webhook.py

References

See references/ for the agent-readable corpus:

• auth (PAT and OAuth)
• pagination patterns
• rate limits
• webhook security model
• product and order payload building notes
• compliance checklist (API terms)