Printful

Printful

This connector talks to the Printful API (https://api.printful.com). Printful prints and ships products on demand (apparel, embroidery, posters, canvas, mugs, phone cases…) from its own fulfilment centres in North America, Europe and elsewhere. A Printful store is either linked to a platform (Shopify, WooCommerce, Etsy, Wix…), whose orders arrive on their own, or a Manual order / API store created in the Printful dashboard.

The connector uses Printful API v1, the documented stable version. Product prices come from the v2 endpoint /v2/catalog-products/{id}/prices, which Printful labels open beta and usable in production.

Setup

1. Sign in at https://developers.printful.com with your Printful account and open Your tokens (https://developers.printful.com/tokens).
2. Create a private token. Pick the access level:
   • Store: the token reaches one store, chosen now. Simplest; store tools need no store_id.
   • Account: the token reaches every store of the account. Store tools then need store_id (from printful_list_stores); it is sent as the X-PF-Store-Id header. Shipping rates and orders need a store too: an account with no store yet answers This endpoint requires store_id, so create one first (Stores → Add store → Manual order platform / API).
3. Pick the scopes. For everything this connector does: orders (read and write orders; orders/read for a read-only setup) and sync_products/read (store products). printful_list_stores needs the stores scope (stores_list) where the token form offers it. The catalog, prices and shipping rates need no scope.
4. Set an expiry date, create the token and copy it right away: it is not shown again. Paste it into PRINTFUL_API_TOKEN.

The token is sent as Authorization: Bearer <token>. Private tokens expire on the date you chose and cannot be refreshed: create a new one before then.

Start here

1. printful_get_token_scopes shows what the token may do; printful_list_stores lists the stores and their ids.
2. Catalog: printful_list_categories → printful_list_catalog_products → printful_get_catalog_product for the variants (size and colour) and their ids; printful_get_product_prices for production prices per placement and technique.
3. Before ordering: printful_calculate_shipping_rates for the shipping options, printful_estimate_order_costs for the full cost of an order.

Orders

• printful_create_draft_order creates a draft: Printful does not submit it for fulfillment and only charges orders that are confirmed. Review it in the dashboard (Orders) and confirm it there or with printful_confirm_order.
• An item is either a catalog variant_id with print files (public image URLs with a placement type such as default or back), or a sync_variant_id / external_variant_id of a product already set up in the store, which carries its own files.
• external_id is your own order id; any order tool also takes it as @<external_id> instead of Printful's numeric id.
• Addresses: country_code is ISO 3166-1 alpha-2; state_code is required for the US, Canada and Australia; a tax number is required for Brazil.
• Statuses: draft (not submitted), pending (submitted, can still be cancelled), inreview, failed, canceled, inprocess (in production), onhold (a problem to resolve), partial (some items shipped), fulfilled (all shipped), archived. Tracking numbers and URLs are in shipments of printful_get_order.
• Orders from a linked Shopify, Etsy or WooCommerce store arrive in Printful by themselves; do not create them again.

Store products

Printful has two product lists, one per store kind:

• Manual order / API stores: printful_list_store_products and printful_get_store_product.
• Platform-linked stores (Shopify, WooCommerce, Etsy…): printful_list_sync_products and printful_get_sync_product, which show which platform variants are synced to a Printful product. Use the pair that matches the kind of store (see type in printful_list_stores).

Responses and paging

Answers have the form { "code": 200, "result": …, "paging": { "total", "offset", "limit" } }. printful_list_orders and printful_list_sync_products page with offset and limit (at most 100). Prices are decimal strings; timestamps are Unix seconds.

Write tools

printful_create_draft_order is on: a draft costs nothing. printful_confirm_order is installed switched off, because confirming charges the store's billing method and starts production; enable it on the connector page if you want it. No tool deletes or cancels anything.

Rate limits

120 requests per minute per store (30 per minute for unauthenticated catalog calls). Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit Printful answers 429 with Retry-After, and the request is not processed.

Errors

• 401: the token is wrong, expired or deleted. Create a new one under Your tokens.
• 403: the token lacks the scope for this call, or an account-level token was used without store_id.
• 400: a field is invalid; the message in result or error.message says which (for example a missing state_code, an unknown variant or a file URL Printful cannot download).
• 404: unknown id. Look ids up with the list tools rather than guessing them.