Printful Management

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

Security Scan

The skill appears to implement a legitimate Printful API helper, but the package metadata fails to declare the required API credential (PRINTFUL_API_KEY), creating an incoherence that users should be aware of before installing.

Purpose & Capability

The skill's name, description, SKILL.md, reference docs, and included script all align with managing a Printful account via the Printful REST API. The helper script targets api.printful.com and implements the expected endpoints and behaviors for listing stores, products, orders, uploads, webhooks, exports, and raw requests.

Instruction Scope

The runtime instructions explicitly instruct obtaining and using a private Printful API token (PRINTFUL_API_KEY) and using the included scripts for both read and write operations. However, the skill's declared requirements list no required environment variables or primary credential, which is inconsistent with the instructions and the script (which resolves token from --api-key or the PRINTFUL_API_KEY env var). The instructions otherwise stay within the Printful management scope and advise safe practices (start with reads, confirm before writes).

Install Mechanism

This is an instruction-only skill with no install spec that ships a helper Python script and Markdown references. There are no network-download install steps, no external package installs described, and no obfuscated or remote payloads in the included files. The script uses only Python stdlib (urllib, json, csv, argparse) and writes/reads local files as expected for exports and body payloads.

Credentials

Functionally the skill legitimately needs a Printful private token to operate; requesting that token is proportionate to the stated purpose. The problem is that the registry metadata lists zero required env vars or primary credentials, while both SKILL.md and scripts rely on PRINTFUL_API_KEY or an --api-key argument. This mismatch could confuse users or automated permission reviewers and increases risk of accidental credential exposure if users are not explicitly warned by the platform UI.

Persistence & Privilege

The skill is not set to always:true and does not request persistent platform-level privileges. It does not modify other skills or global agent settings. It can perform write operations to the Printful account (create/update/delete) but the SKILL.md states that writes should be confirmed with the user first.

What to consider before installing

This package contains a helper script that talks directly to api.printful.com and requires the user's Printful private token (the script reads --api-key or PRINTFUL_API_KEY). The registry metadata did not declare any required environment variables or a primary credential — that's an inconsistency you should be aware of. Before installing or running: (1) review scripts/printful_api.py yourself to confirm there are no unexpected network endpoints (it uses https://api.printful.com only), (2) supply the API token via an ephemeral environment variable (as recommended) rather than hardcoding, (3) run read-only commands first (stores, sync-products, orders) to verify behavior, (4) be cautious with webhook URLs or write actions and confirm every mutation before proceeding, and (5) consider rotating the token after use. If you want stronger assurance, ask the publisher to update the package metadata to declare PRINTFUL_API_KEY as a required credential so automated reviewers and other users will see the dependency clearly.

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:

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:

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:

$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:

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:

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:

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.