Connect Printful to Fondoo

What Fondoo can do with it

Fondoo uses Printful's v1 API. Actions, used through connector_action:

• Read: catalog.list and catalog.get (Printful's catalog products and variants), shipping.rates (shipping options for a recipient and items), orders.get and tracking.get (order details, including shipments).
• Write: products.create (a Printful store product with your print files).
• Money (owner approval for agents): orders.create.

Orders are drafts by default. Fondoo creates the order with confirm=false unless the order data has confirm: true. Printful doesn't charge for draft orders. A confirmed order goes straight to fulfillment, and Printful charges the store owner's billing method (Printful API). Only confirm an order on purpose.

Fondoo's commerce tools also use the connection:

• import_supplier_product: create a draft product in your Shopify or WooCommerce store from a Printful variant. Printful catalog prices can leave out print and placement costs. So pass a supplierQuote with the real unit cost, shipping and a reference whenever you can. Fondoo then prices from that instead of the catalog price.
• route_order_to_supplier: send a real store order to Printful. Fondoo fills in the recipient from the store order and a stable external_id. You supply the items with variant IDs and print files in supplierData. They must match the store order exactly. This always needs the owner's approval.
• get_order_tracking: refresh tracking and give the customer a public tracking link.

Before you start

• A Printful account at printful.com. API access is free. You pay for orders you confirm.
• A billing method in Printful (card or wallet), so confirmed orders can be charged.
• A Printful store. Store-level tokens are tied to one store. Account-level tokens need the store ID sent with each request.
• Your print files, hosted at public URLs, ready for products and orders.

Step by step: get your credentials

1. Sign in to the Printful Developer Portal and open Your tokens: https://developers.printful.com/tokens.
2. Create a new private token. Name it Fondoo.
3. Choose the access level:
   • A single store (simplest): the token only works for that store.
   • Account level: works for all stores. You must then give Fondoo the store ID.
4. Choose scopes (scopes):
   • orders: create and read orders.
   • sync_products: create store products.
   • file_library: optional, only if you will use files from your Printful library. Catalog and shipping-rate reads don't need extra scopes.
5. Pick an expiry date. Printful tokens expire and can't be refreshed, so set a reminder to replace it.
6. Create the token and copy it now. Printful won't show it again.
7. If you chose account level, note the store ID. You can see it in Printful's store settings, or ask the agent to read it after connecting.

What goes where:

Connect it in Fondoo

In the dashboard

1. Open Connections.
2. Under Available, find Printful (in the Suppliers group) and click Use a key.
3. Click Open secure key entry (single use, expires after 15 minutes). Paste the token (and store ID), then save.
4. Click Check connection on the new card.

By asking your agent

Example prompt:

Connect my Printful account. Send me a secure link for the token, then show me Printful's t-shirt catalog.

The agent calls:

add_connection_key({ provider: "printful", siteId: "<site id>" })   // secure paste link
test_connection({ connectionId: "<id>" })
connector_action({ connectionId: "<id>", action: "catalog.list", input: {} })

For a help link only: connect_service({provider:"printful", siteId}) (signed, valid 15 minutes).

Over REST: POST https://api.getfondoo.com/v1/ops/<operation> with Authorization: Bearer <your Fondoo API key> and the same JSON, for example POST /v1/ops/add_connection_key with {"provider":"printful","siteId":"<site id>"}.

Test that it works

1. Run test_connection. It reads your store list. All actions show as "unknown" until used. That's expected, because Printful doesn't report a token's scopes.
2. Run catalog.get for one product and shipping.rates for a sample address.
3. Create a draft order (orders.create without confirm: true). Check it in your Printful dashboard, then delete or confirm it there.

Troubleshooting

• 401 Unauthorized. The token is wrong or expired. Printful tokens can't be refreshed. Create a new one and run rotate_connection_key.
• Error asking for a store ID. You used an account-level token without storeId. Add the store ID with rotate_connection_key, or use a store-level token.
• 403 or a scope error. The token lacks orders or sync_products. Create a new token with those scopes.
• "POD items and quantities must match the imported supplier variants...". The items in supplierData must have the same variants and quantities as the store order, plus print files.
• Order stuck in draft. That's the default. Confirm it in Printful, or resend with confirm: true after approval.
• 429 Too Many Requests. Printful allows 120 requests per minute, and only 10 per minute for creating store products (rate limits). Fondoo keeps to 60 actions per minute.

Limits, data and security

• What Fondoo stores: the token, encrypted and never shown again. The store ID is stored as a plain identifier. Fondoo also keeps import mappings, routed order IDs and tracking status.
• API version: Fondoo uses Printful's v1 API. Printful says v1 still works but may be phased out later, and its v2 is still labelled beta.
• Rotate: create a new token, run rotate_connection_key({connectionId}), then delete the old token in Your tokens.
• Disconnect: delete_connection({connectionId}) removes the stored token (owner approval for agents). Then delete the token in Printful.

Official links

• Printful API docs (auth, scopes, rate limits, orders): https://developers.printful.com/docs/
• Private tokens: https://developers.printful.com/tokens
• Printful API v2 (beta): https://developers.printful.com/docs/v2-beta/