# Printful setup for PopMCP

You end up with one Printful private token, created in the Printful Developer Portal, that you paste into PopMCP's Private token field.

- Auth: API credentials
- Setup time: 5 min
- API base URL: https://api.printful.com
- Credentials screen: https://developers.printful.com/tokens
- Provider docs: https://developers.printful.com/docs/

## Before you begin

- A Printful account with at least one store already created.
- Sign-in rights to that account. The Developer Portal logs you in through Printful's own OAuth screen.
- A contact email for the token. The form requires one.
- Decide whether the token covers one store or the whole account. Account-level tokens need an X-PF-Store-Id header on store endpoints.
- Private tokens carry an expiry date and cannot be refreshed, so plan to replace the token before it lapses.

## Get your credentials

### 1. Sign in to the Printful Developer Portal

Go to developers.printful.com and click Sign in to Printful. Approve the Printful sign-in screen to land back in the portal.

Screen: https://developers.printful.com/login

### 2. Open Tokens and add a new one

In the left menu click Tokens, then click Add new token.

Screen: https://developers.printful.com/tokens

### 3. Fill in the details, expiry and access level

Enter PopMCP under Token name and an address under Contact email. Pick an Expiration date, then choose A single store and select your store from the dropdown.

Screen: https://developers.printful.com/tokens/add-new-token

### 4. Tick the scopes and create the token

Under Scopes tick Orders, Sync products and File library, plus Webhooks if PopMCP should manage subscriptions. Click Create new token.

### 5. Copy the access key into PopMCP

Copy the value in the Access key panel, then paste it into PopMCP's Private token field.

## Fields PopMCP asks for

- Private token (apiToken) [required]: In Printful, open the Developer Portal (developers.printful.com) → Your tokens → create a private token, grant the scopes you need (orders, sync products, file library, webhooks, …), and copy it (it is shown only once). Sent as an Authorization: Bearer header, stored encrypted, used server-side only.

## Verify

The Printful connector in PopMCP shows Connected and a catalog or store-information call returns your store name rather than a 401.

## Troubleshooting

### 401 Unauthorized

Cause: The token expired, was deleted in the Developer Portal, or the Bearer prefix got mangled on paste.

Fix: Check the Expires on date under Your tokens and create a replacement if it has lapsed.

### You navigated away before copying the access key

Cause: The Access key panel shows the secret once, and Printful does not store it.

Fix: Delete the token under Your tokens and create a new one.

### 403 on a specific endpoint while others work

Cause: That endpoint needs a scope the token was not granted, or you granted the read-only variant.

Fix: Create a new token with the missing scope. Scopes cannot be added to a token after creation.

### Calls fail with a missing store error

Cause: An account-level token was used on an endpoint that needs store context.

Fix: Create a store-level token for the store you want, or make sure PopMCP is configured to send X-PF-Store-Id.

### 429 Too Many Requests

Cause: More than 120 calls in a minute, or a stricter per-endpoint limit such as the mockup generator.

Fix: Back off and retry. Batch mockup generation rather than firing requests in parallel.

---

Source: https://www.docs.popmcp.com/docs/integrations/printful/