# Printful

Source: https://developers.swell.is/app-guides/printful

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.

## How it works

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

## Before you begin

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

## Set up

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.

**1. 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.

**2. 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.

**3. Add the token to the app**

In Swell, go to **Apps > Printful > Settings**, paste the token into **Printful API token** and click **Save settings**.

**4. 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.

**5. 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.

**6. 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.

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

## Using Printful

### Keeping products in sync

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

### Fulfilling orders

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

### Retrying a failed order

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.

> **Warning:** Do not reset a job whose state is **Confirmed**. Printful has already charged your account for it.

### In the dashboard

| 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

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 |

## Limitations

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

## Troubleshooting

### No Printful rates at checkout

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.

### This Printful token is for your whole account

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.

### Products do not appear in Swell

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 stay as drafts in Printful

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.

### Shipments and tracking do not appear on orders

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

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

## For 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.

```sh
swell api post /functions/printful/product-sync-run
```

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

## Support

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.