# printify-api

> 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.

- Author: Diffbro Developer
- Repository: J-DTurner/printify-api-skill
- Version: 20260125155521
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/J-DTurner/printify-api-skill
- Web: https://mule.run/skillshub/@@J-DTurner/printify-api-skill~printify-api:20260125155521

---

---
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)