Skill: stanestane/printful-management (version 1.1.0)

--- name: printful-management description: Manage a Printful account through the Printful REST API using a private API token. Use when the user wants to inspect or manage Printful stores, connected-store sync products, manual/API-store products, variants, orders, product templates, file library items, shipping rates, webhooks, mockups, warehouse products, tax endpoints, approval sheets, reports, or exports; when building a local Printful integration; or when converting seller requests like "list my Printful items", "show my stores", "export my products to CSV", "update this synced variant", "create a mockup task", or "configure Printful webhooks" into safe API calls. --- # Printful Management Use this skill to work with a user's Printful account via API token instead of brittle browser login. ## Quick start 1. Get a Printful private token from the user. 2. Prefer storing it in the current shell as `PRINTFUL_API_KEY` instead of hardcoding it into files. 3. Use `scripts/printful_api.py` for live calls. 4. Start with safe read calls: - `stores` - `sync-products` for connected-platform stores like Etsy - `manual-products` for Manual Order / API stores - `orders` 5. Before write operations, summarize the exact mutation and wait for confirmation unless the user already clearly asked for the change. ## Core workflow ### 1. Identify the seller task Classify the request into one of these buckets: - **Stores**: inspect stores, get store IDs - **Connected-store products**: list sync products or variants for Etsy and similar platform-connected stores - **Manual/API-store products**: create or manage products for Manual Order / API stores - **Orders**: list orders, inspect one order, create draft orders, confirm fulfillment - **Catalog**: inspect Printful catalog products, variants, categories, and size guides before creating store products - **Files / mockups**: upload artwork, inspect file library, generate mockups - **Webhooks**: inspect or configure webhook delivery - **Shipping / tax**: quote shipping, inspect tax-country support, calculate tax rates - **Reporting / warehouse / approvals**: pull stats, warehouse product data, or approval sheet actions If the request is vague, ask one short clarifying question. ### 2. Start read-only Prefer these discovery calls first: ```powershell python scripts/printful_api.py stores python scripts/printful_api.py sync-products --store-id <id> python scripts/printful_api.py orders --store-id <id> ``` If `sync-products` fails with a Manual/API-store style error, switch to: ```powershell python scripts/printful_api.py manual-products --store-id <id> ``` These usually reveal the IDs needed for later write calls. ### 3. Handle auth safely Prefer ephemeral auth in the shell: ```powershell $env:PRINTFUL_API_KEY = 'pf_xxx' ``` The helper script also accepts `--api-key`, but environment variables are better because they reduce accidental logging and file leakage. ### 4. Use the helper script `scripts/printful_api.py` wraps a broad set of Printful endpoints and also supports arbitrary API requests. Common reads: ```powershell python scripts/printful_api.py scopes python scripts/printful_api.py stores python scripts/printful_api.py store --store-id 12345 python scripts/printful_api.py sync-products --store-id 12345 --limit 100 python scripts/printful_api.py sync-product --store-id 12345 --product-id 67890 python scripts/printful_api.py manual-products --store-id 12345 --limit 100 python scripts/printful_api.py orders --store-id 12345 --limit 50 python scripts/printful_api.py order --store-id 12345 --order-id 111 python scripts/printful_api.py catalog-products --limit 20 python scripts/printful_api.py catalog-product --product-id 71 python scripts/printful_api.py catalog-variant --variant-id 4011 python scripts/printful_api.py categories python scripts/printful_api.py templates --store-id 12345 python scripts/printful_api.py webhooks --store-id 12345 python scripts/printful_api.py statistics --store-id 12345 python scripts/printful_api.py export-products --store-id 12345 --format markdown --output-file report.md python scripts/printful_api.py export-products --store-id 12345 --format csv --output-file products.csv ``` Common writes: ```powershell python scripts/printful_api.py create-manual-product --store-id 12345 --body-file product.json python scripts/printful_api.py update-sync-variant --store-id 12345 --variant-id 999 --body-file variant.json python scripts/printful_api.py create-order --store-id 12345 --body-file order.json python scripts/printful_api.py confirm-order --store-id 12345 --order-id 111 python scripts/printful_api.py add-file --store-id 12345 --body-file file.json python scripts/printful_api.py set-webhooks --store-id 12345 --body-file webhook.json python scripts/printful_api.py create-mockup-task --store-id 12345 --body-file mockup.json ``` Raw requests: ```powershell python scripts/printful_api.py raw GET /stores python scripts/printful_api.py raw GET /sync/products?limit=10 --store-id 12345 python scripts/printful_api.py raw POST /webhooks --store-id 12345 --body-file webhook.json ``` Notes: - The script uses the modern `X-PF-Store-ID` header for store context. - Responses are pretty-printed JSON. - `--output file.json` also saves the response to disk. - `export-products` can generate markdown, CSV, or JSON summaries for store products. - Non-2xx responses return a non-zero exit code. ## Mutation rules For create/update/delete operations: 1. Confirm the target store, product, variant, order, or template ID. 2. Show the exact endpoint family and payload in plain language. 3. Mention that the change affects live Printful data. 4. Prefer draft or test-safe operations first when available. 5. Respect rate limits; Printful docs indicate a general limit of 120 API calls per minute. ## Common endpoint map Use this quick map before reaching for raw mode: - **Stores** - `GET /stores` - `GET /stores/{id}` - **Connected-platform sync products** - `GET /sync/products` - `GET /sync/products/{id}` - `GET /sync/variants/{id}` - `PUT /sync/variants/{id}` - `DELETE /sync/variants/{id}` - **Manual/API-store products** - `GET /store/products` - `GET /store/products/{id}` - `POST /store/products` - `PUT /store/products/{id}` - `DELETE /store/products/{id}` - `GET /store/variants/{id}` - `POST /store/variants` - `PUT /store/variants/{id}` - `DELETE /store/variants/{id}` - **Orders** - `GET /orders` - `GET /orders/{id}` - `POST /orders` - `PUT /orders/{id}` - `DELETE /orders/{id}` - `POST /orders/{id}/confirm` - `POST /orders/estimate-costs` - **Catalog** - `GET /products` - `GET /products/{id}` - `GET /products/variant/{id}` - `GET /products/{id}/sizes` - `GET /categories` - `GET /categories/{id}` - **Product templates** - `GET /product-templates` - `GET /product-templates/{id}` - `DELETE /product-templates/{id}` - **Webhooks** - `GET /webhooks` - `POST /webhooks` - `DELETE /webhooks` - **Mockups** - create task - get task result - get printfiles - get layout templates - **Reports / warehouse / approvals** - statistics - warehouse product list/detail - approval sheet list/actions If exact payload fields matter, read `references/printful-api-notes.md`, `references/request-examples.md`, and, if needed, the official docs page the user supplied. ## Response style When reporting account data back to the user: - Summarize first. - Then list IDs, names, statuses, and counts. - Do not dump giant raw JSON unless the user asked for it. - If products are "for sale", distinguish between catalog products and the user’s synced store products. - Call out whether the store is likely a connected-platform store or a Manual/API store if that changes which endpoint family applies. ## Publication hygiene If the user wants the skill published to ClawHub: 1. Ensure no secrets or local dumps live inside the skill folder. 2. Validate and package the skill. 3. Use the `clawhub` CLI to publish the **skill folder**, not random extra workspace files. 4. Do not publish until the user explicitly wants the live publish action. ## Local reference Read `references/printful-api-notes.md` when you need a compact refresher on auth, endpoint-family selection, rate limits, and publication hygiene. Read `references/request-examples.md` when you need starter JSON bodies for common writes.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)