Printful Orders & Products
Run a print-on-demand shop on Printful: quote shipping rates and order costs before checkout, place draft orders for your synced products, confirm them for fulfillment, and look up an order's status and tracking shipments without opening the dashboard.
Connect this API to an AI agent Browse all specs
What you can do with Printful Orders & Products via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /products |
listCatalogProducts | Browse Printful's catalog of blank products |
| GET | /products/{id} |
getCatalogProduct | Get a catalog product with its variants (sizes, colors) |
| GET | /products/variant/{id} |
getCatalogVariant | Get one catalog variant with price and stock |
| GET | /store/products |
listStoreProducts | List your store's synced products |
| GET | /store/products/{id} |
getStoreProduct | Get a synced product with its variants and print files |
| POST | /shipping/rates |
calculateShippingRates | Quote shipping options and prices for an address and items |
| POST | /orders/estimate-costs |
estimateOrderCosts | Estimate product, shipping and tax costs before ordering |
| GET | /orders |
listOrders | List orders, optionally by status |
| POST | /orders |
createOrder | Create a draft order (or submit it with confirm=true) |
| GET | /orders/{id} |
getOrder | Get an order's status, costs and shipments |
| PUT | /orders/{id} |
updateOrder | Change a draft order's recipient or items |
| POST | /orders/{id}/confirm |
confirmOrder | Submit a draft order for fulfillment (charges your account) |
Authentication
bearerAuth
Bearer token — sent as Authorization: Bearer <token>
How to get a credential
- Sign in to the Printful Developer Portal (developers.printful.com) with your Printful account.
- Open Your tokens → Create token.
- Choose Single store access (recommended) and the store, set an expiry date, and tick the scopes below.
- Copy the token; it is shown once. An Account level token also works but then every store-specific call needs the
X-PF-Store-Idheader.
Permissions used
| Scope | Operations |
|---|---|
| (none) | listCatalogProducts, getCatalogProduct, getCatalogVariant, calculateShippingRates |
| sync_products/read | listStoreProducts, getStoreProduct |
| orders/read | listOrders, getOrder |
| orders | estimateOrderCosts, createOrder, updateOrder, confirmOrder |
Common errors
- 401 Unauthorized: the token expired or was deleted; create a new one.
- 403 Forbidden: a scope above is missing, or an account-level token was used without
X-PF-Store-Id. - 400 Bad Request: invalid recipient address, an unknown
variant_id/sync_variant_id, or a missing print file. - 429 Too Many Requests: 120 requests per minute; wait and retry.
Store the token as a VX Agents credential (Bearer token).
Usage guide
Setup
- Credential: a Printful private token from the Developer Portal (Your tokens), stored as a Bearer credential. Prefer a single-store token; with an account-level token, send the
X-PF-Store-Idheader on store calls. - Worth pinning:
X-PF-Store-Idwhen using an account-level token.
Quote, place and confirm an order
listStoreProducts→getStoreProductto find thesync_variant_idof what the customer bought (products already designed in your store). For a blank catalog item, uselistCatalogProducts→getCatalogProduct→getCatalogVariantfor thevariant_idand send a print file URL infiles.calculateShippingRateswithrecipient(address1,city,country_code,state_codefor US/CA/AU,zip) anditems(variant_idorsync_variant_id,quantity) to show shipping options (STANDARD,EXPRESS, ...).estimateOrderCostswith the same recipient and items for product, shipping and tax totals.createOrderwithrecipient(plusname,email),items,shipping(the chosen rate id) and your ownexternal_id. Leaveconfirmoff: the order is created as a draft and nothing is charged.updateOrderto fix the address or items while it is still a draft.confirmOrdersubmits the draft for fulfillment and charges your Printful balance or card: only after the user approves the costs.listOrders(filterstatus:draft,pending,inprocess,fulfilled, ...) andgetOrderfor status, costs andshipmentswith tracking numbers and URLs.
Always confirm with the user before confirmOrder or createOrder with confirm=true: they spend money. Confirm before updateOrder as it changes customer data.
Good to know
- An order id can be the Printful id or your external id prefixed with
@(e.g.@SHOP-1042). - Money amounts are strings in the order currency (
"12.95"). - Lists page with
offsetandlimit(max 100). - Catalog calls (
listCatalogProducts,getCatalogProduct,getCatalogVariant) need no scope. - Rate limit: 120 requests per minute per token; on 429 wait and retry.
Source: Printful API reference (https://developers.printful.com/docs/), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Printful Orders & Products” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.