App guides
The Printful app connects a Printful store to your Swell store for print-on-demand fulfillment. Products you design in Printful are created in Swell, and paid orders are sent to Printful to be printed and shipped. Shoppers see Printful shipping rates at checkout, and each Printful shipment is added to the Swell order with its tracking number.
The app works with any storefront. Everything it adds is a standard Swell record: the synced products, the shipping services on the cart, and the shipments on the order.
| When | What the app does |
| Every hour, or when you run a sync | Creates and updates Swell products from the products in your Printful store. |
| A shopper gets shipping rates at checkout | Adds Printful's rates for the Printful items in the cart next to your own shipping services. |
| An order is paid | Creates the order in Printful as a draft. If live fulfillment is on, the app confirms the draft once Printful has calculated its costs, and Printful starts production. |
| Printful ships an order | Adds a shipment with the carrier, service and tracking number to the Swell order, within about 10 minutes. |
| Printful rejects an order | Marks the order failed and emails your store admins. The Printful dashboard shows why. |
Printful charges your Printful account when an order is confirmed. Drafts are free. The app confirms orders only in the live environment, and only while Live fulfillment is on.
Only the Printful items in an order are sent to Printful. Other items in the same order are fulfilled the way they normally are.
Orders reference the Printful product you designed, so Printful prints the files stored with that design. After you change a design in Printful, later orders print the new version.
The app checks each confirmed order in Printful every 10 minutes until Printful has fulfilled or canceled it, so there is nothing to register in Printful.
- A Printful store of the Manual order platform / API type. Your products are designed in this store.
- A private Printful API token with access to that store only, and the orders and sync_products scopes. Tokens for a whole Printful account are not supported.
- A separate token for the test environment. App settings, including the token, are saved per environment.
Install Printful from the Swell App Store, and set it up in your test environment before the live one. Orders placed in the test environment are never confirmed at Printful, so you can check the whole flow without printing or paying for anything.
Design your products in Printful
In Printful, add a store of the Manual order platform / API type. Design your products in that store: pick a product, place your artwork, generate mockups and set your retail prices.
Create a Printful API token
In Printful, go to Settings > Developers and create a private token with access to that store only. Give it the orders and sync_products scopes.
Add the token to the app
In Swell, go to Apps > Printful > Settings, paste the token into Printful API token and click Save settings.
Enable Printful shipping rates
Go to Settings > Shipping, turn on the Printful row and click Save changes. Installing the app does not turn it on, and until it is on, checkout shows only your own shipping services.
Sync your products
On the app page, choose Actions > Sync products now, or wait for the hourly sync. The sync runs in the background, one product at a time, and the app page shows its progress. Each Printful product becomes a Swell product, with its colors and sizes as variants, Printful's mockups as photos and your Printful retail prices.
Products are created as drafts. Review the name, description and prices of each product, then make it active.
Place a test order
With Live fulfillment off, a paid order is created in Printful as an unconfirmed draft. Place an order for a Printful product, open the order's Printful tab, and use View in Printful to check the items, sizes and print files of the draft.
Go live
In the live environment, repeat steps 2 to 5 with a new token. Then turn on Live fulfillment in the app settings.
Orders paid while Live fulfillment was off stay as drafts. To send one for production, set its fulfillment job back to Pending as described in Retrying a failed order.
- The sync runs every hour. To sync right away, choose Actions > Sync products now on the app page, Sync now in the app settings, or Sync from Printful in the actions of the Products list. Each syncs every new and changed product in the background, and the Runs tab on the app page shows its progress.
- To re-read particular products, choose Resync from Printful on a product, or select products in the Products list and choose Resync from Printful.
- A color or size added in Printful is added to the Swell product as a variant. A variant removed or discontinued in Printful is made inactive.
- A product deleted or ignored in Printful is made inactive in Swell and kept for order history.
- To stop selling a product, delete or ignore it in Printful. Deleting it only in Swell does not stop the sync, and the next run creates it again as a draft.
- After the first sync, the name, description, prices and photos are yours to edit in Swell, and the sync does not overwrite them. A variant added later gets its Printful retail price when it is first linked.
- Swell creates a variant for every combination of color and size. Combinations Printful does not offer are made inactive.
- To replace a product's photos with Printful's latest mockups, select the product in the Products list, choose Resync from Printful and turn on Replace photos with Printful mockups.
- The hourly sync uses up to 30 Printful requests per run and handles new products first, so a large store catches up over several hourly runs. A manual sync handles every new and changed product in one background run, and waits whenever Printful's rate limit is reached.
- Paid orders that contain Printful items are sent to Printful automatically. Only the Printful items are sent.
- Printful can ship an order in several parts. Each part is added to the Swell order as its own shipment, with its carrier, service and tracking number.
- The app checks each confirmed order in Printful every 10 minutes until Printful has shipped or canceled it, so a shipment appears on the Swell order within about 10 minutes of shipping.
- When Printful cancels an order, the new status appears on the order's Printful tab. The Swell order is not canceled or refunded.
A fulfillment fails when Printful rejects the order, or when 8 attempts in a row end in an error. The order's Printful tab shows the last error, and your store admins receive an email. When Printful rejects an order, open it in Printful to see why. Printful checks print files after an order is confirmed, so an order can fail after Printful has accepted it.
Failed orders are listed on the Printful failed tab of the Orders list, and their jobs on the Failed tab of Orders > Printful fulfillments.
To retry, fix the cause, then open the job in Orders > Printful fulfillments, set State to Pending, clear Next attempt and save. The job runs again right away.
Do not reset a job whose state is Confirmed. Printful has already charged your account for it.
| Location | What it shows |
| Order > Printful tab | The Printful order ID and status, the submission state, when the order was confirmed, a link to the order in Printful, and the last error. |
| Orders list > Printful failed tab | Orders whose Printful submission failed. |
| Orders > Printful fulfillments | One fulfillment job per order, with Failed, In flight and Confirmed tabs. |
| Product > Printful tab | The Printful product the Swell product was created from, and when it last synced. |
| Products list > Printful tab | Products synced from Printful. |
| Products > Printful variants | The Swell variant each Printful variant is sold as. The sync maintains these links. |
| App settings | Last product sync and Last sync result, with a Sync now button. |
Settings are in Apps > Printful > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Printful API token | Private token for your Manual order platform / API store, with the orders and sync_products scopes. Use a different token in each environment. | None |
| Live fulfillment | When off, paid orders are created in Printful as drafts and are not confirmed. When on, drafts are confirmed for production in the live environment, which charges your Printful account. | Off |
| Fallback shipping rate | Flat rate offered at checkout when Printful is slow, rate-limited or unreachable. Leave it empty to offer no Printful rate when a quote fails. | None |
| Fallback service name | Name of the fallback rate at checkout. | Standard shipping |
| Quote cache lifetime | Seconds a shipping quote is reused for the same destination and cart, from 0 to 3600. Set it to 0 to turn caching off. | 300 |
| Rate request timeout | Milliseconds to wait for a Printful quote before using the fallback rate, from 1000 to 9000. | 6000 |
| Last product sync, Last sync result | When the product sync last ran and what it did, including errors. Read-only. | Set by the app |
- Printful allows 120 API requests per minute across everything the app does. Checkout quotes, order submission, order tracking and the product sync all share this limit.
- When Printful is near its rate limit, slow or unreachable, checkout offers the fallback rate, or no Printful rate if none is set.
- Printful's rates cover only the Printful items in the cart. In a cart that also contains other products, the shopper chooses one shipping service for the whole order, so a Printful rate does not include shipping for the other items.
- Cancellations at Printful are shown on the Swell order but not applied to it. Cancel or refund the Swell order yourself if needed.
- Shipments and failures reach Swell within about 10 minutes, when the app next checks the order.
- Refunds made in Printful are not shown in Swell.
- Prices are copied from Printful as numbers, without currency conversion. If your Printful and Swell stores use different currencies, set the prices in Swell.
- Product photos are loaded from Printful's CDN rather than copied into Swell.
- Only products in the Printful store that the token belongs to are synced.
Check that the Printful row under Settings > Shipping is turned on and saved. Printful rates are offered only for carts that contain products synced from Printful and have a shipping address. If Printful does not answer within the Rate request timeout and no fallback rate is set, no Printful rate is offered.
The token has access to your whole Printful account instead of one store. Create a token with access to your Manual order platform / API store only, and paste it into the app settings.
Check Last sync result in the app settings for the error. A token without the sync_products scope cannot read your Printful products, so create a new token with the orders and sync_products scopes. Synced products are created as drafts and are listed on the Printful tab of the Products list.
Orders are confirmed only in the live environment with Live fulfillment on. Until then, the fulfillment job shows "Held as a draft" in Last error. After you turn on Live fulfillment, set the job back to Pending to confirm the order.
The app checks confirmed orders every 10 minutes, so a shipment can take that long to appear. If it still doesn't, open the order's job under Orders > Printful fulfillments and check its Last error.
Uninstalling the app stops the product sync, Printful rates at checkout, order submission and tracking updates. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Before you uninstall, turn off the Printful row under Settings > Shipping and save. The row is not listed once the app is uninstalled.
Products and shipments the app created are standard Swell records and stay in your store.
Uninstalling does not change anything at Printful. Orders already created in Printful stay there, including unconfirmed drafts. If you are not going to reinstall the app, delete its token in Printful under Settings > Developers.
The app stores its data under $app.printful on orders, products and shipments, and in two collections of its own.
| Model | Field | Description |
| orders | printful_order_id | ID of the Printful order. |
| orders | printful_status | Latest status reported by Printful, such as draft, pending, fulfilled, canceled or failed. |
| orders | submit_state | State of the fulfillment job: pending, created, calculating, confirmed or failed. |
| orders | confirmed_at | When the order was confirmed at Printful. |
| orders | dashboard_url | Link to the order in the Printful dashboard. |
| orders | last_error | Most recent Printful error for the order. |
| products | sync_product_id | ID of the Printful product the Swell product was created from. |
| products | date_synced | When the product last matched Printful. |
| shipments | shipment_id | ID of the Printful shipment the Swell shipment was created from. |
| shipments | tracking_url | Tracking link reported by Printful. |
| Collection | Description |
| apps/printful/fulfillments | One job per paid order that contains Printful items, with its state, Printful order ID and status, attempt count and last error. |
| apps/printful/sync-variants | Links each Swell variant to its Printful sync variant and catalog variant. |
The product sync runs every hour. To run it from a script, call the product-sync-run function. The optional budget sets how many Printful requests the run can use, and defaults to 30.
swell api post /functions/printful/product-sync-runEach fulfillment job checks its confirmed order in Printful every 10 minutes, reading the order and its shipments, until Printful has fulfilled or canceled it. A scheduled job every 10 minutes restarts any check that was missed. There is no webhook to register.
Swell builds and maintains the Printful app. For help with the app, email support@swell.is. For questions about your Printful account, products, printing or deliveries, contact Printful.