# name: stable skill identifier used by routers, manifests, and audit tooling.
name: printify
# description: routing-facing summary of what the skill covers and when it activates.
description: "Use when working with Printify — the print-on-demand REST API, catalog model (blueprints, print providers, variants, print areas), product creation and publish lifecycle to connected channels, order routing, shipping cost queries, and HMAC SHA-256 webhook verification. Do NOT use for non-Printify POD vendors, generic Shopify storefront work, or print-file (artwork) generation."
# license: SPDX-compatible license identifier for the skill content.
license: CC-BY-4.0
# metadata: Skill Metadata Protocol fields encoded under Agent Skills-compatible frontmatter.
metadata:
# === v8 Classification (subject + public; polyhierarchy via subjects[]) — see ADR-0017 ===
# subject: primary browse shelf — what the skill teaches. One of twelve closed values:
# backend-engineering / frontend-engineering / software-architecture / data-engineering / agent-ops / ai-engineering /
# quality-assurance / design / reasoning-strategy / software-engineering-method / knowledge-organization / product-domain.
subject: product-domain
# public: publishability/private-data gate. Boolean.
# true = publishable/shareable; false = private and excluded from public export.
# Project anchoring is carried separately by non-empty `project[]` plus `grounding`.
public: true
# scope: free-text PRD-style statement of what the skill teaches and what it excludes.
# (v8 required; not an enum). Mirrors Coverage + Do NOT Use When at frontmatter level.
scope: "Use when working with Printify — the print-on-demand REST API, catalog model (blueprints, print providers, variants, print areas), product creation and publish lifecycle to connected channels, order routing, shipping cost queries, and HMAC SHA-256 webhook verification. Do NOT use for non-Printify POD vendors, generic Shopify storefront work, or print-file (artwork) generation."
subjects: [product-domain, backend-engineering]
# taxonomy_domain: optional hierarchical sub-path within `subject`. Slash-delimited
# lowercase kebab-case segments. rename of the original v8 `domain`. Remove when the flat
# `subject` is sufficient.
taxonomy_domain: engineering/integrations
# stability: lifecycle marker. One of:
# experimental (active development) / stable (production-ready) /
# frozen (no further changes expected) / deprecated.
# When `deprecated`, schema's allOf REQUIRES `superseded_by: <real-skill-name>`.
stability: experimental
# keywords: semantic phrases for fuzzy router activation. v8 cap: max 10.
# Keep terms a user would actually type when starting a task in this skill's domain.
keywords: ["printify api","print on demand","printify blueprints","printify print providers","printify publish lifecycle","printify webhooks","printify variants","printify shipping costs","printify order routing","print provider catalog"]
# triggers: explicit-match activation phrases the router fires on literally.
# Use when label-based routing is intended; usually keywords + examples are enough.
triggers: ["printify","printify api","printify webhook","print on demand"]
# grounding: required when `project[]` is non-empty. Declares the truth sources
# the skill anchors to and the failure modes those sources prevent. Omit when the
# skill is universal-knowledge. `subject_matter` replaces v8 `domain_object`.
grounding: "{\"subject_matter\":\"Printify API catalog, product publish lifecycle, orders, shipping, and webhook verification\",\"grounding_mode\":\"universal\",\"truth_sources\":[\"https://developers.printify.com/\",\"https://developers.printify.com/#catalog\",\"https://developers.printify.com/#products\",\"https://developers.printify.com/#orders\",\"https://developers.printify.com/#shipping\",\"https://developers.printify.com/#webhooks\"],\"failure_modes\":[\"blueprint_and_print_provider_treated_as_independent_variant_spaces\",\"publish_request_treated_as_synchronous_channel_success\",\"webhook_signature_verified_from_parsed_json_instead_of_raw_body\",\"shipping_cost_estimate_treated_as_final_order_cost\",\"shopify_sync_boundary_misrouted_to_printify_skill\",\"artwork_generation_misclassified_as_printify_api_work\"],\"evidence_priority\":\"general_knowledge_first\"}"
# examples: 2-5 realistic user prompts the skill SHOULD activate for.
# Written in the user's voice. Improves retrieval recall beyond keywords alone.
examples: ["Create a Printify product from a blueprint + print provider + variant set and publish it to a connected Shopify store","Handle a Printify order:updated webhook and reconcile fulfillment status","Resolve shipping cost for a basket of Printify variants given a destination country"]
# anti_examples: near-miss prompts that should route ELSEWHERE.
# Pair with relations.suppresses (or legacy boundary alias) to name the confusable territory's owner.
anti_examples: ["Generate the artwork PNG file that gets uploaded as a print file","Implement the Shopify side of the Printify-to-Shopify sync","Design a generic POD-vendor-agnostic product schema"]
# === Export provenance (set by the export pipeline; do not hand-author) ===
# skill_graph_protocol is a content-label claim distinct from `schema_version` semantics.
# See AGENTS.md § Version Labels Are Earned, Not Bumped.
skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
skill_graph_project: Skill Graph
skill_graph_canonical_skill: skills/product-domain/printify/SKILL.md
# relations: typed graph edges to sibling skills.
relations:
related: ["webhook-integration","api-design","shopify"]
suppresses: ["shopify"]
Use when working with Printify — the print-on-demand REST API, catalog model (blueprints, print providers, variants, print areas), product creation and publish lifecycle to connected channels, order routing, shipping cost queries, and HMAC SHA-256 webhook verification.
The Printify REST API exposes a catalog (blueprints — abstract product templates like "Unisex Heavy Cotton Tee"; print providers — fulfillment partners who manufacture a given blueprint; variants — concrete color/size combinations a provider offers for a blueprint), shops (connected sales channels: Shopify, Etsy, WooCommerce, eBay, TikTok, custom API), products (a blueprint + print provider + variant selection + print areas + images, owned by a Printify shop), and orders (created either by sync from a connected channel or directly via API for merchant-fulfilled flows). This skill covers the relationships between these resources and the lifecycle transitions that move a product from draft to published to live on a storefront.
Authentication is a personal access token in the Authorization: Bearer header. The API is versioned via URL path (currently /v1/) and rate-limited globally with documented limits per endpoint family — product creation is more constrained than read calls. Image uploads go through a dedicated upload endpoint that accepts either a public URL or base64 contents and returns an image ID referenced by subsequent product-create payloads.
The publish lifecycle is a two-step asynchronous operation. POST to /products marks a product as ready for publish in Printify; the actual push to the connected channel (e.g., creating the Shopify product) happens via /products/{id}/publish which returns immediately and resolves asynchronously. The channel push can fail independently (channel auth expired, blueprint not available in the target region) and must be observed via the publishing-succeeded / publishing-failed webhook events or by polling the product publish status. Unpublish and delete each have their own semantics — unpublish removes from the channel but keeps the product in Printify; delete removes both.
Webhooks deliver order, product, and shop events. Each delivery includes an X-Pfy-Signature header computed as HMAC SHA-256 over the raw body with the webhook secret returned on subscription. Order events (order:created, order:updated, order:sent-to-production, order:shipment:created, order:shipment:delivered, order:cancelled) carry the full order payload including line items with print provider, shipping cost, and tracking. Shipping cost can also be computed pre-purchase via /shops/{shop_id}/orders/shipping.json with a destination address and line items.
Printify sits between the merchant and the print provider, and its catalog reflects that — a blueprint's available variants and print areas are determined by the print provider, not by Printify. The same blueprint produced by two providers can have different color availability, different print area dimensions, and different shipping profiles. Integrations should treat blueprint + print_provider as a composite key and never assume that variants are portable across providers.
The publish lifecycle is asynchronous and partially observable. Treat publish success as a separate state from product-create success, and reconcile via webhooks rather than optimistic UI. Costs (product cost, shipping cost) are determined at order-create time by Printify and can differ from any pre-quoted estimate; the order webhook payload is the source of truth for actual cost.