Printful

Log in to your Printful account at printful.com. Navigate to Settings in the top-right account menu. In Settings, click 'Stores' in the left sidebar, then select the store you want to connect to Bubble. Under the store settings, look for the 'API' tab or 'API Access' section. Click 'Enable API Access' if it is not already enabled. Printful generates an API token unique to this store. Copy it immediately — this token provides full API access to your Printful store data and order management. Alternatively, for account-level access across all your Printful stores, go to Settings → API (the top-level account setting, not a specific store). An account-level token lets you manage multiple stores from the same Bubble app — recommended if you plan to expand to multiple storefronts. Do not paste this token anywhere in your Bubble app's frontend code, data fields, or page states. You will add it directly to the Bubble API Connector as a Private header value in the next step.

1// Printful API token format:
2// Your token is a long alphanumeric string (example format):
3// 7f3k9m2p1q8r5n6t4w0x
4
5// Base URL for all Printful API calls:
6// https://api.printful.com
7
8// Quick test (browser console or REST client):
9// GET https://api.printful.com/stores
10// Authorization: Bearer YOUR_TOKEN_HERE
11//
12// Expected response:
13// { "code": 200, "result": [ { "id": 123456, "name": "My Store", ... } ] }

In your Bubble editor, go to Plugins tab → API Connector. If API Connector is not installed, click 'Add plugins' → search 'API Connector' → Install it (it's free, by Bubble). Click 'Add another API' and name it 'Printful.' Set the base URL to `https://api.printful.com`. Do NOT add a trailing slash. In the shared headers section for this API group, add: - Header name: `Authorization`, Value: `Bearer YOUR_TOKEN_HERE` — paste your actual Printful token, then check the **Private** checkbox. This is the most important step: Private means Bubble sends this header only from its servers, never from the user's browser. - Header name: `Content-Type`, Value: `application/json` Now add your first API call for initialization. Click 'Add another call' and name it 'Get Stores.' Set method to GET and URL to `/stores`. This is a simple endpoint that returns your Printful store list — safe to use as an Initialize Call because it never creates or modifies data. Click 'Initialize call.' You should see a JSON response like `{ "code": 200, "result": [ { "id": 123456, "name": "My Store", ... } ] }`. Bubble maps the detected fields including `result.[0].id` and `result.[0].name`. If the Initialize call returns an empty response or error, check that the Authorization header includes 'Bearer ' followed by your token with no extra spaces.

1// Printful API Connector configuration:
2// API name: Printful
3// Base URL: https://api.printful.com
4//
5// Shared Headers:
6// Authorization: Bearer YOUR_PRINTFUL_TOKEN   // mark Private
7// Content-Type: application/json
8//
9// Initialize Call: GET /stores
10// Expected response:
11// {
12//   "code": 200,
13//   "result": [
14//     {
15//       "id": 123456,
16//       "name": "My Bubble Store",
17//       "type": "manual",
18//       "website": "https://myapp.bubbleapps.io"
19//     }
20//   ]
21// }

With the Printful connector initialized, add the product catalog calls. Click 'Add another call' under the Printful API group and name it 'Get Sync Products.' Set method to GET and URL to `/sync/products`. Add parameters: - `store_id` (text, optional) — your Printful store ID; add it if you have multiple stores - `limit` (text, default '20') — products per page, maximum 100 - `offset` (text, default '0') — pagination offset Click Initialize call. Printful returns a response like `{ "code": 200, "result": [ { "id": 1234, "name": "Classic T-Shirt", "thumbnail_url": "https://..." } ], "paging": { "total": 45, "limit": 20, "offset": 0 } }`. Bubble maps response fields under `result.[n].id`, `result.[n].name`, `result.[n].thumbnail_url`. Note: **all mappings must start with `result.`** — this is Printful's response wrapper pattern. For individual product details including variants (sizes, colors, prices, mockup images), add another call named 'Get Sync Product Detail.' Set method GET, URL `/sync/products/<id>` where `<id>` is a dynamic text parameter. The response includes `result.sync_product` (product info) and `result.sync_variants` (array of all variants with variant_id, sku, retail_price, and files). On your Bubble storefront page, add a Repeating Group. Set its data source to 'Plugins → API Connector → Printful → Get Sync Products' and map `result` as the list. In each cell, bind: - Product name: current cell's `name` field - Image: current cell's `thumbnail_url` field (use Bubble's Image element, URL source) - On cell click: navigate to a product detail page, passing the product `id` as a URL parameter

1// Printful → Get Sync Products
2// Method: GET
3// URL: https://api.printful.com/sync/products
4//
5// Parameters:
6// limit: 20
7// offset: <dynamic: pagination_offset state variable>
8//
9// Response structure:
10// {
11//   "code": 200,
12//   "result": [
13//     {
14//       "id": 1234567,
15//       "name": "Classic Unisex T-Shirt",
16//       "thumbnail_url": "https://files.cdn.printful.com/files/...",
17//       "is_ignored": false
18//     }
19//   ],
20//   "paging": { "total": 45, "limit": 20, "offset": 0 }
21// }
22
23// Printful → Get Sync Product Detail
24// Method: GET
25// URL: https://api.printful.com/sync/products/<id>
26//   (<id> = dynamic text parameter for product ID)
27//
28// Response:
29// {
30//   "code": 200,
31//   "result": {
32//     "sync_product": { "id": 1234567, "name": "Classic Unisex T-Shirt" },
33//     "sync_variants": [
34//       {
35//         "id": 9876543,
36//         "name": "Classic Unisex T-Shirt / S / Black",
37//         "retail_price": "29.99",
38//         "sku": "MYSTORE-TSHIRT-S-BLACK",
39//         "files": [ { "type": "preview", "preview_url": "https://..." } ]
40//       }
41//     ]
42//   }
43// }

The most critical workflow sequence in a POD storefront is: Stripe payment confirmed → Printful order placed. Always confirm payment first — Printful charges your Printful wallet immediately when an order is created. Add a new API Connector call named 'Place Printful Order.' Set method POST, URL `/orders`. Set the body type to 'JSON body.' The required fields are `recipient` (customer shipping address) and `items` (array of ordered variants with quantities). In Bubble, this POST call body must be constructed dynamically using the API Connector's JSON body parameters. Add these top-level parameters to the call: - `recipient` (object type) — you'll need to use a JSON text parameter and build the object string dynamically - Alternatively, use Bubble's 'Body (raw)' option and build the full JSON as a dynamic text expression For the 'Body (raw)' approach, set content type to JSON and build the body text dynamically in Bubble's expression editor: ``` {"recipient":{"name":"[Customer Name]","address1":"[Street]","city":"[City]","state_code":"[State]","country_code":"US","zip":"[Zip]"},"items":[{"sync_variant_id":[Variant ID],"quantity":[Quantity]}]} ``` In your Stripe payment workflow, after the payment step confirms success (Stripe webhook received or Stripe.js payment confirmed), add this Printful order action. Map customer fields from your Bubble User data type and the selected variant ID from the cart state. Initialize the call with a real test payload — use your personal address and a real sync_variant_id from your Printful catalog. Printful will create a real draft order (set `draft: true` in the body during testing to prevent automatic fulfillment).

1// Printful → Place Order
2// Method: POST
3// URL: https://api.printful.com/orders
4// Body type: JSON (raw)
5//
6// Body:
7{
8  "recipient": {
9    "name": "<dynamic: Customer's name>",
10    "address1": "<dynamic: Customer's street address>",
11    "city": "<dynamic: Customer's city>",
12    "state_code": "<dynamic: Customer's state, 2-letter code>",
13    "country_code": "US",
14    "zip": "<dynamic: Customer's zip code>",
15    "email": "<dynamic: Customer's email>",
16    "phone": "<dynamic: Customer's phone>"
17  },
18  "items": [
19    {
20      "sync_variant_id": <dynamic: selected Printful sync_variant_id>,
21      "quantity": <dynamic: quantity from cart>
22    }
23  ],
24  "retail_costs": {
25    "currency": "USD",
26    "subtotal": "<dynamic: cart subtotal>",
27    "shipping": "<dynamic: selected shipping rate>",
28    "total": "<dynamic: cart total>"
29  }
30}
31
32// Add 'draft: true' during testing to prevent auto-fulfillment:
33// {
34//   "draft": true,
35//   "recipient": { ... },
36//   "items": [ ... ]
37// }

Show customers real shipping rates from Printful before they complete checkout. Printful's `/shipping/rates` endpoint accepts a recipient address and items array and returns all available shipping options with rates and delivery estimates. Add a call named 'Get Shipping Rates.' Set method POST, URL `/shipping/rates`. Build the JSON body with `recipient` (same structure as the order body — address fields) and `items` (array of objects with `quantity`, `variant_id`, and `value` — the retail price used for insurance). Call this endpoint when the customer lands on the checkout page or after they enter their shipping address. Display the returned array of rate options in a Repeating Group or Dropdown, showing carrier name, service level, rate (cost), and estimated delivery window. Store the customer's selected shipping option in a custom state variable (carrier name and rate amount), then include `retail_costs.shipping` in the Printful order POST body when placing the order. This ensures Printful's records show the correct shipping charge collected. Note: Printful shipping rates are calculated based on the recipient's location and the package dimensions of the specific variants ordered. Rates change frequently — always fetch them live rather than caching them, so customers see accurate costs.

1// Printful → Get Shipping Rates
2// Method: POST
3// URL: https://api.printful.com/shipping/rates
4//
5// Body:
6{
7  "recipient": {
8    "address1": "<dynamic: entered street address>",
9    "city": "<dynamic: entered city>",
10    "state_code": "<dynamic: entered state>",
11    "country_code": "US",
12    "zip": "<dynamic: entered zip code>"
13  },
14  "items": [
15    {
16      "quantity": <dynamic: cart quantity>,
17      "variant_id": <dynamic: Printful variant_id (not sync_variant_id)>,
18      "value": "<dynamic: item retail price as string>"
19    }
20  ],
21  "currency": "USD",
22  "locale": "en_US"
23}
24
25// Response:
26// {
27//   "code": 200,
28//   "result": [
29//     {
30//       "id": "STANDARD",
31//       "name": "Flat Rate (3-4 business days after fulfillment)",
32//       "rate": "3.99",
33//       "currency": "USD",
34//       "minDeliveryDays": 3,
35//       "maxDeliveryDays": 4
36//     },
37//     {
38//       "id": "EXPRESS",
39//       "name": "Express (1-2 business days after fulfillment)",
40//       "rate": "7.99",
41//       "currency": "USD"
42//     }
43//   ]
44// }

Printful sends webhook events to notify your Bubble app when orders change status — the most important events are `package_shipped` (with tracking number) and `order_updated` (status changes). To receive these, you need a Bubble Backend Workflow endpoint. First, ensure the Workflow API is enabled: go to Settings → API → check 'This app exposes a Workflow API.' Your app's workflow endpoint base URL will be shown (format: `https://yourapp.bubbleapps.io/api/1.1/wf/`). In the Backend Workflows section of your Bubble editor, click 'Add workflow' and name it `printful_webhook`. Add the 'Detect request data' trigger — Bubble will listen for the next incoming POST request to map the schema. In Printful, go to your store settings → Webhooks. Click 'Add webhook,' paste your Bubble endpoint URL (`https://yourapp.bubbleapps.io/api/1.1/wf/printful_webhook`), and select the events: 'Package shipped' and 'Order updated' (at minimum). Save the webhook. Printful sends a test webhook ping immediately. In Bubble's Backend Workflows Detect Data mode, it will capture this payload. The Printful webhook payload contains `type` (event type string), `data.order` (full order object including `status`, `shipment_tracking`, and `recipient`), and `data.shipment` (for shipping events, includes `tracking_number`, `tracking_url`, `carrier`, `service`). Add actions to your Backend Workflow: use 'Make changes to Thing' to update your Order Data Thing (find the order by Printful's order ID), set the status field, and if the event type is 'package_shipped,' save the tracking number and URL. Finally, trigger any customer notification workflows (email via SendGrid, or push notification). RapidDev's team routinely builds this exact fulfillment pipeline — for complex multi-variant setups, reach out at rapidevelopers.com/contact.

1// Bubble Backend Workflow URL for Printful webhooks:
2https://yourapp.bubbleapps.io/api/1.1/wf/printful_webhook
3
4// Printful webhook payload (package_shipped event):
5// {
6//   "type": "package_shipped",
7//   "created": 1737982853,
8//   "retries": 0,
9//   "store": 123456,
10//   "data": {
11//     "shipment": {
12//       "id": 9876543,
13//       "status": "shipped",
14//       "tracking_number": "1Z999AA10123456784",
15//       "tracking_url": "https://www.ups.com/track?tracknum=...",
16//       "created": 1737982850,
17//       "ship_date": "2026-01-27",
18//       "shipped_at": 1737982850,
19//       "reshipment": false,
20//       "carrier": "UPS",
21//       "service": "UPS Ground"
22//     },
23//     "order": {
24//       "id": 111222333,
25//       "external_id": "BUBBLE-ORDER-456",
26//       "status": "fulfilled",
27//       "shipping": "STANDARD"
28//     }
29//   }
30// }
31
32// NOTE: 'created' timestamps in Printful webhooks are Unix seconds
33// To display as a readable date in Bubble, store as text and display
34// or multiply by 1000 in a Run JavaScript action to convert to milliseconds