Integration
Printful Integration
Print on demand fulfilment connected to paid orders, with variant mapping, order references, tracking and deliberate handling of uncertain submission results.
- Apparel and accessory ranges launched without inventory risk
- Merchandise lines for creators, clubs and events
- Mixed catalogues where some lines are stocked and others are printed
- Limited runs tested before committing to production
- International shipping handled from regional fulfilment locations
Overview
What this integration involves
Printful produces and ships items after they are sold. The integration turns an order in your system into a production job, keeps status in step, and returns tracking to the customer.
Two details decide whether it works in production. The first is variant mapping: your product variant has to resolve to exactly one fulfilment variant, and a silent mismatch ships the wrong size. The second is idempotent submission, because a retry that creates a second job costs real money.
The third consideration is mixed fulfilment. Most stores end up shipping some lines from their own stock, so routing has to be per line rather than per order.
Surface
Capabilities we use
Catalogue and variants
The fulfilment catalogue of products, variants, sizes, colours and placement options, used to build and validate the mapping against your own catalogue.
Print files and mockups
Artwork uploaded per placement with position and scale, and generated mockups used as product imagery so the store shows what will actually be produced.
Order submission
Orders created with recipient address, line items resolved to fulfilment variants, and an external reference carrying your order identifier.
Shipping rate quoting
Rates requested for the actual basket and destination at checkout, rather than a flat estimate that is wrong in both directions.
Status and tracking
Production and shipment events returned by webhook, written to the order and surfaced to the customer.
Mixed fulfilment
Per line routing so an order can split between print on demand and your own stock, with tracking merged into one customer view.
Data flow
Step by step
- 01
Map the catalogue
Each of your variants is mapped to exactly one fulfilment variant and stored. The mapping is validated at build time so a product cannot be published without one.
- 02
Quote shipping at checkout
A rate request is made for the basket and destination, with a short timeout and a cached fallback so a slow response does not block checkout.
- 03
Create the order on payment
The verified payment webhook creates the order in your system. Submission to fulfilment is a separate queued step, so a fulfilment outage never loses a paid order.
- 04
Submit idempotently
Persist a stable external reference and the provider order ID. Serialize submission for each order and reconcile an uncertain response through the provider API before retrying. A reference is useful for lookup, not a substitute for duplicate prevention in the integration.
- 05
Track status
Webhooks report the job moving into production, shipping and delivery. Each event updates the order and can notify the customer.
- 06
Reconcile
A scheduled job lists recent fulfilment orders and compares them against your paid orders, catching anything submitted but stalled or never submitted at all.
Architecture
How the pieces connect
- 01StorefronttoCommerce service
checkout
- 02Commerce servicetoPostgreSQL
create order
- 03Commerce servicetoFulfilment queue
enqueue. Asynchronous delivery.
- 04Fulfilment queuetoVariant mapping
resolve variants
- 05Fulfilment queuetoPrintful
submit with reference
- 06PrintfultoCommerce service
status webhooks. Asynchronous delivery.
- 07Commerce servicetoCustomer email
tracking. Asynchronous delivery.
Events
Webhooks we handle
- Order created and confirmed, acknowledging the job entered production
- Order failed, usually a print file or address problem that needs a person
- Package shipped, carrying the carrier and tracking number
- Order returned or undeliverable, which needs a customer service action
- Product updated, signalling a catalogue change that may invalidate a mapping
Reliability
What makes it hold
External reference on every submission
Keep the local order, external reference and provider ID together. After a timeout, check whether the job exists before another create or confirm attempt. Use bounded exponential backoff for retryable failures and route unresolved outcomes to review.
Submission decoupled from checkout
The paid order is recorded first and submitted by a worker. A fulfilment outage delays production rather than losing an order.
Mapping validated at build time
A product whose variant has no fulfilment mapping fails the build rather than reaching the store and failing at the most expensive moment.
Rate quoting with a fallback
A short timeout with a cached or table based fallback, because a slow rate call at checkout costs conversions.
Failed jobs surface to a person
Print file rejections and address failures are not retryable by machine. They route to an operations queue with the reason attached.
Reconciliation catches the silent cases
A stalled job produces no webhook. A scheduled comparison between paid orders and fulfilment orders is what finds it before the customer does.
Security
How it is secured
- API keys held in the platform secret store and used only from server code.
- Verify the documented webhook signature where the selected API version supports signing. For unsigned notifications, retrieve the referenced order through the authenticated API before changing trusted state.
- Recipient addresses transmitted over TLS and stored under your normal retention policy.
- No payment data is shared with the fulfilment provider.
- Print artwork stored in object storage you own, with the provider given time limited access.
FAQ
Questions people actually ask
What stops a retry printing a second shirt?
Stable references, stored provider IDs and serialized submission work together. After an uncertain response, the integration checks the provider record before repeating an operation. A reference alone does not make every request safe to repeat.
Can we mix printed and stocked items in one order?
Yes. Routing is per line, and tracking from both paths is merged so the customer sees one order with the shipments it actually has.
How accurate is shipping at checkout?
Rates are quoted for the real basket and destination. Where the call is slow we fall back to a cached or table rate rather than holding up checkout, and the difference is absorbed rather than passed on later.
What happens when a print file is rejected?
The job fails with a reason and routes to an operations queue. That failure needs a person, so it is not retried automatically.
Do customers know it is print on demand?
That is your decision. The integration supports branded packing slips where the provider offers them, and dispatch timing is communicated from the real production estimate rather than a promise you cannot keep.
What if the provider changes a product?
A product update webhook flags the mapping for review, and a mapping that no longer resolves fails the build rather than shipping the wrong item.
Let’s talk about the system you need.
Tell us where the current process breaks down. We can map the workflow, examine the integration requirements and define a practical scope for the build.
- A mutual NDA is signed before project details are shared.
- Scope is fixed in writing before any build starts.
- You own the source code, the IP and the documentation at delivery.
- Support plans are available and tailored on a discovery or technical call.