Print on Demand (Prodigi)¶
Sell posters, prints, cards, mugs and similar products that are printed only when someone orders them. The shop holds no stock: when an order arrives, Badger sends the print files and the delivery address to Prodigi, who print and post it, and Prodigi reports dispatch and tracking back so the customer gets the usual dispatch email.
It is built on fulfillers: a Prodigi fulfiller is a fulfiller whose type is
PRODIGI, told through Prodigi's API instead of by email, Slack or the portal.
Setting it up¶
- Open a Prodigi account and, in its dashboard under API settings, copy an API key. A
sandbox dashboard (sandbox-beta-dashboard.pwinty.com)
gives test keys and the live dashboard real ones. Sandbox orders are never printed, shipped or
charged, so start there. If the key starts
test_, it's the old format: regenerate it. - Connect it in Settings. Under Settings > Integrations > Prodigi print on demand set:
- Prodigi API key (a secret; it is never shown again once saved).
- Prodigi mode:
sandboxorlive, matching the dashboard the key came from. The dashboard shows the key without its mode, so Badger sends it assandbox_<key>orlive_<key>; Prodigi refuses a live key sent as a sandbox one (or the reverse), so a trial shop can't place paid orders by mistake. A key pasted with its prefix must match the mode. Both modes use the same Prodigi address; the key decides which one you are talking to. - Prodigi webhook secret: lets Badger check that dispatch and tracking updates really come from Prodigi (see below).
- Prodigi shipping method:
budget,standard,standardplus,expressorovernight(defaultstandard). Faster costs more, and what is available depends on the product and the address. - Only products made in the UK (on by default): the catalogue search, and so the products you can add, are limited to Prodigi products made and sent from the UK, so UK customers never pay customs charges on delivery.
- Add a fulfiller. Under Shop Settings > Fulfillers create a fulfiller and choose Prodigi as its type. The email, Slack and portal routes don't apply to it and are hidden. Assign the products Prodigi prints to this fulfiller.
- Tell Prodigi where to send updates. Prodigi reports progress by webhook to
https://<your shop domain>/api/public/v1/fulfilment/webhooks/prodigi/<your shop's key>. The address is specific to your shop. Connect webhook on Orders > Print on demand (or the MCP actionmanagePodProducts connectWebhook) registers it with Prodigi for the order and shipment events, saves the signing secret Prodigi returns and asks Prodigi to send a test event, saying if it didn't arrive. It does nothing if a secret is already saved. (You can instead register the address in the Prodigi dashboard and paste the secret into Prodigi webhook secret.) Until a secret is saved every update is refused. Badger also checks on orders itself (see Dispatch below), so dispatch and tracking still reach the customer without the webhook, only later.
Note
The Prodigi API reference documents webhooks for the version of the API Badger uses, but Prodigi's own FAQ says they are not available, and in the sandbox only the test event arrived: no order or shipment updates. Badger doesn't depend on them: it re-reads orders that have gone quiet every 15 minutes.
The Print on demand page¶
Once the shop has a working Prodigi key, Orders > Print on demand appears in the admin sidebar (admins only). It shows:
- Connection: sandbox or live, whether dispatch updates (the webhook) are connected, with a Connect webhook button while they aren't, the shipping method, whether only UK-made products are offered, and the Prodigi fulfiller. Without a working key the page says what to fix (no key, or a key that doesn't match the Prodigi mode) and links to the settings.
- Print orders needing you: the same orders the ops inbox counts (never sent, held, paused, failed, left as a draft, cancelled by Prodigi, not cancelled at Prodigi, stuck for over an hour, or on its way but unchanged for two weeks), oldest first, each linking to its order with what to do about it.
- Cost prices: Sync costs now runs the cost sync for this shop straight away and says how many costs were updated.
Mapping products¶
Each Badger product or variant SKU is mapped to a Prodigi SKU, together with the artwork to print and any options (such as colour or size). A product with no mapping can't be sent: its order stops with a "send failed" status and an alert instead of being lost.
On the product page¶
For shops with a working Prodigi key, the product edit page has a Print on demand card (admins only; merchandisers don't see it, because it shows Prodigi's prices, which are the shop's cost prices). It lists every SKU the product sells (its variants, or the product itself when it has none) with its selling price and how it is printed. To map one, open Map to Prodigi under it:
- Find a Prodigi product by name (with Only products made in the UK on, only UK-made products and SKUs are listed), then choose the size or SKU. You can also type a Prodigi SKU you know.
- Choose its Options (such as colour and size) and Print area. Only Prodigi's own combinations are offered.
- Choose artwork from the media library. Prodigi fetches it from its public address, so it must be served over HTTPS.
- While you choose, the card asks Prodigi for its price and shows it against the selling price: Prodigi's item price plus VAT, shipping for one, and what is left before shipping. It turns red when the selling price is below Prodigi's price.
- Save mapping. The same rules as the MCP
mapaction apply: the SKU needs a price at least Prodigi's price plus VAT, the product's name and description must pass the blocked-words check, the shop needs exactly one active Prodigi fulfiller, and a SKU that needs artwork on two print areas is refused. The product moves to the Prodigi fulfiller only once every SKU it sells is mapped; until then it keeps its fulfiller and the card says how many are left. - Artwork resolution is checked as you save, the way Prodigi checks it: the image's pixels over the print area's size, since the artwork fills the area. Under half the print area's recommended dpi (Prodigi's "will look pixelated") the mapping is refused and the message says how many pixels would print sharp. Under the recommended dpi it is mapped with a warning that the print may look a little soft. JPEG, PNG and TIFF files up to 60 MB are checked; a PDF, a larger file, or a print area whose size Prodigi doesn't publish is mapped with a note that it wasn't checked.
Stop printing with Prodigi removes a SKU's mapping. When no SKU of the product is mapped any more, it is taken off the Prodigi fulfiller and has no fulfiller until you assign one.
Creating a new print product from the Prodigi catalogue (with mock-ups made from the artwork) is still done through MCP.
Through an AI agent¶
You can also create the mappings by asking an AI agent through MCP (below), which looks the Prodigi catalogue up, uploads the artwork, makes mock-ups, and creates the product and its mappings in one go.
What happens to an order¶
- Submit. When an order is submitted (or imported from a marketplace), the lines assigned to an active Prodigi fulfiller are queued and sent to Prodigi in the background, so checkout never waits for Prodigi. This is its own pipeline step, on for every shop: it doesn't depend on the optional email fulfilment step. Prodigi charges the shop as soon as it accepts an order, so an order not yet paid for (a shop that captures payment at pack or dispatch) is captured first; if that fails, nothing is sent and it is raised. A failed send is retried with a delay; the same order is never created twice at Prodigi, because every attempt uses the same idempotency key. If no answer ever came back, Badger asks Prodigi whether it made the order anyway (by the order number) before calling it failed. An order still queued an hour later is queued again and raised. The customer's email and phone number are not sent to Prodigi.
- Dispatch. When a shipment leaves Prodigi's lab, Badger dispatches the fulfiller's lines with the carrier and tracking number from Prodigi and the customer receives the normal dispatch email. See Dispatch, Cancellations & Returns. Badger hears about it from Prodigi's webhook or, failing that, from its own check: every 15 minutes it asks Prodigi about the orders still on their way that haven't changed for 10 minutes, so dispatch reaches the customer within about 15 minutes of the parcel going even if no webhook arrives. The check also notices an order put on hold (and raises it, once) and one that comes off hold. It reads at most 50 orders per shop each time, those it checked longest ago first (so orders that never change, such as a batch on hold, can't crowd out newer ones), well inside Prodigi's limit of 1,000 calls an hour. It stops for the shop if Prodigi says to slow down, refuses the key, fails or doesn't answer, and stops checking an order once it is completed or cancelled, or 30 days after it was sent. An order on its way that hasn't changed for two weeks (say Prodigi no longer knows it) is in the ops inbox. An order cancelled in Badger while a check is running is left cancelled.
- Cancellation. Cancelling an order whose lines went to Prodigi also cancels the print
order, but only while Prodigi still allows it. The check comes first: once printing has started,
the cancellation is refused with a message saying so and the order is left as it was. The print
order is cancelled only after the refund has gone through, so a cancellation that fails on the
payment leaves the print order alone. While the order is being sent to Prodigi the cancellation
asks you to try again in a minute; a send whose answer never came is looked up at Prodigi first.
An order not sent yet is marked so it is never sent. If Prodigi refuses at the last moment
(production started in between), the customer has been refunded, the print order is marked
cancel_failedand raised: cancel it in Prodigi.
When something goes wrong¶
Prodigi orders that couldn't be sent, are on hold, paused, failed, left as a draft with a
problem, cancelled by Prodigi, or not cancelled at Prodigi when the Badger order was, raise an alert
in Badger's operations Slack channel naming the site and order (once, when it happens), as does a
shipment exception; the Badger order itself is not changed. They are written to the order's
activity history (PRODIGI_ORDER_CREATED, PRODIGI_ORDER_SEND_FAILED,
PRODIGI_ORDER_NEEDS_ATTENTION, PRODIGI_ORDER_CANCELLED, PRODIGI_ORDER_NOT_CANCELLED). The
MCP ops inbox has a prodigiOrdersNeedingAttention count of the same statuses,
plus orders still queued, being sent or pending submission after an hour and orders on their way
that haven't changed for two weeks, shown only for shops that
use Prodigi; podCatalogue orders lists them with the reason.
Costs¶
A nightly job (03:20) asks Prodigi's quote service for the price of every mapped SKU and writes
the result as the product's cost price, so margin can be measured on printed
products. It runs only for shops with an active Prodigi fulfiller, and an agent can trigger it for
one shop with syncCosts or an admin with Sync costs now on Orders > Print on demand. Costs are written as the pounds-and-pence Prodigi quotes, with no
currency conversion, so use it on shops that sell in GBP. It also needs the Enterprise
merchandisingRules entitlement that cost prices need.
Through MCP¶
Two tools, added to the MCP server:
podCatalogue(mcp:read):searchthe Prodigi catalogue, list a product'svariants(SKUs, options, print areas, sizes), list this shop'smappings, and the printordersthat need someone.managePodProducts(mcp:write):quoteProdigi's prices (items, shipping and VAT apart, for the UK; these are the shop's costs, so they need the write scope),uploadArtwork, makemockups,createProduct(disabled until you enable it),mapandunmapa SKU,syncCostsandconnectWebhook.
map maps one SKU. Fulfilment is assigned per product, so the product moves to the Prodigi
fulfiller only once every SKU it sells is mapped; until then it keeps its fulfiller and the answer
lists the SKUs still to map.
createProduct is refused if the price is below what Prodigi would charge, if the artwork would
print pixelated on any of its sizes (the same resolution check as the admin, above), or if the
name or description contains words for brands, characters, teams, bands, real people, or children's
products. map refuses pixelated artwork too, and both say in their note when it is only soft or
couldn't be checked. The blocked-words list is a built-in starter list: it will occasionally refuse an innocent
word and doesn't look at the artwork itself.
Not built yet¶
- A resend action for an order that failed to send (after fixing an unmapped SKU or the card on the Prodigi account). The send can be repeated safely; nothing in the admin does it yet.
- Replacing a webhook whose secret was lost (clear the secret and delete the webhook in Prodigi first).
- Creating a print product from the catalogue in the admin (with mock-ups): it is MCP only.
- A shipment exception is raised but not counted in the ops inbox.
- When one Prodigi order ships in several parcels, only the first shipment's carrier and tracking is passed to the customer, and all the fulfiller's outstanding lines are dispatched together.
- The admin and MCP cancellation preview doesn't know about Prodigi: an order can look cancellable until the cancellation itself is refused.
- International shipping: the customs value isn't sent, and the shop is set up for UK delivery only.
- Site deletion leaves the shop's product mappings and Prodigi order links behind (they hold no
personal data). They aren't part of site data transfer, and the whole
prodigi-configgroup (API key, webhook secret, mode and the rest) is site-bound. - Print quality depends on the full-size artwork URL returning the original file; check it with a sandbox order.
For developers¶
All in commerce-core, package fulfilment/prodigi, unless noted.
ProdigiClientoverProdigiHttp(JdkProdigiHttp): Print API v5 calls and rate-limit handling.ProdigiCredentialsandProdigiAccountServiceread the secrets fromprodigi-configand check the key against the mode.- The request and response models are generated from Prodigi's published OpenAPI spec, vendored
unedited at
commerce-core/src/main/openapi/prodigi-v5.yml(itsREADME.mdgives the source, fetch date and how to update it), into packagefulfilment/prodigi/v5at build time. Where the API and the spec disagree, the API wins: every enum is a plain String (the sandbox sends shipment statusesInProgressandShipped), and a shipment'sitemson an order, objects in the spec but item id strings from the API, read asProdigiShipmentItem, which takes either.ProdigiV5has the helpers on top (pence, never-null lists, the ids Badger put in an order's metadata).ProdigiSandboxFixturesTestparses what the sandbox really sent (src/test/resources/prodigi/v5). PodProductMapping,PodProductMappingService: Badger SKU to Prodigi SKU, artwork and options.ProdigiOrderLink,ProdigiOrderLinkService: one row per Badger order sent, with the Prodigi order id and last status.- Sending:
SubmitProdigiOrderProcessor(submitOrderandimportChannelOrder, on by default) callsProdigiFulfilmentNotifier.queue, which publishes aProdigiOrderMessagethroughProdigiOrderPublisheronto the queues inProdigiQueueConfig(the notifier is still thePRODIGIFulfilmentNotifier, but itsnotifyFulfillerdoes nothing, so the email fulfilment step never queues twice). The worker'sProdigiOrderListenercallsProdigiOrderSubmitter, which builds the request withProdigiOrderRequestBuilder, marks the linksendingbefore the call, and looks an unanswered send up withProdigiOrderFinder(GET /orders?merchantReference=) before giving up.ProdigiOrderLinkis versioned, so the worker, a cancellation and a webhook can't overwrite each other's changes. The worker'sProdigiStaleOrderSweepJobrunsProdigiStaleOrderSweeperevery 15 minutes (badger.prodigi.stale-sweep-enabled,badger.prodigi.stale-sweep-interval-ms).ProdigiOrderAlerterandProdigiAttentionServiceraise and count problems;ProdigiOrderStatusesholds the one list of statuses both go by. - Applying Prodigi's state:
ProdigiOrderSyncServicetakes an order asGET /orders/{id}returned it and dispatches (any shipmentdispatched,in_transit,shippedordelivered, compared ignoring case), records the link status and alerts, for both the webhook and the refresh. A refresh is judged against the link as saved at that moment (ProdigiOrderLinkService.recordRefresh), not as the run loaded it, so a link Badger cancelled during the run is left alone. One that finds nothing new only setslastRefreshedAt(a targeted update that moves neitherupdatednor the version), so a link's age still tells the ops inbox how long it has been quiet. A webhook and the refresh can see the same parcel at once, so before dispatching each claims the link (ProdigiOrderLinkService.claimDispatch, one conditional write ofdispatchClaimedAt): only the one that wins dispatches and the customer gets one dispatch email. A claim lasts 5 minutes (so a pod that dies mid-dispatch doesn't block it) and is given up at once if the dispatch fails; a later claim finds nothing left to move. - Refreshing: the worker's
ProdigiOrderRefreshJobrunsProdigiOrderRefresherfor every shop with a working key. It reads links inProdigiOrderStatuses.IN_FLIGHT(pending_submission,submitted,in_production,partially_shipped,shipped,on_hold,paused; neverdraft,failed,completed, cancelled or Badger's own statuses) throughProdigiOrderLinkService.findQuiet, never refreshed first, then bylastRefreshedAt, so every link gets its turn. Settings:badger.prodigi.order-refresh-enabled(true),-interval-ms(900000),-initial-delay-ms(420000),-quiet-minutes(10),-max-age-days(30) and-max-reads-per-site(50). A 429, a refused key, a 5xx or no answer stops that shop's run; a read that fails otherwise (a 404) moves that link to the back. The Redis lock holds a token and is released only by its holder (compare-and-delete), and a run starts no read after 7 minutes, inside the lock's 10, so two workers never refresh at once.ProdigiAttentionServicealso countsIN_FLIGHTlinks unchanged forProdigiOrderStatuses.IN_FLIGHT_STALE_AFTER(14 days). - Cancelling:
CancelProdigiOrderProcessorchecks (validate phase) andCompleteProdigiCancellationProcessorcancels at Prodigi after the refund (core phase), in thecancelOrderandcancelOrderPartpipelines. - Receiving:
ProdigiWebhookController(rest, inapi.yamlunder/api/public/v1/fulfilment/webhooks/prodigi/{siteKey}) hands the raw body toProdigiWebhookService, afterProdigiWebhookVerifierchecks theX-Prodigi-Signatureheader (t=<unix seconds>, v1=<hex>, HMAC-SHA256 oft.bodywith the webhook secret). It re-reads the order and applies it throughProdigiOrderSyncService; any event whose re-read shows a shipment gone dispatches, not only the shipment events.ProdigiWebhookService.registersubscribes the shop's address and stores the secret. - Costs:
ProdigiCostSyncService, run by the worker'sProdigiCostSyncJob(badger.prodigi.cost-sync-enabled,badger.prodigi.cost-sync-schedule). - Admin rules:
PodProductService(catalogue search, a SKU's options, quotes,mapandunmap, refusing withPodProductException, whose reason is theadmin.pod.error.*message key) andPodContentCheck, the blocked-words check. - Admin (
web-admin, packagerender/admin/printondemand):PrintOnDemandAdminController(/admin/print-on-demand, the page and the card's map/unmap forms),PrintOnDemandRestAdminController(/admin/api/print-on-demand, the card's search, options and quote calls),PodProductPanels(the product page's card, built byProductAdminRenderer). The sidebar entry followsNavVisibility.printOnDemand, set byAdminNavServicefromProdigiAccountService.isConfigured. Text is underadmin.pod.*inmessages.properties. - MCP:
PodToolsin theaimodule. Itsmap,unmapandcreateProductcallPodProductService(map,unmap,createProduct), so the admin and the MCP tools apply one set of rules;PodTools.refusalturns aPodProductExceptioninto a tool error with a hint on what to do next. - Artwork resolution:
PodArtworkCheckerfetches the artwork throughSafeHttpFetcher, reads its size withImageDimensionsand judges it against the variant'sprintAreas(widthMm,heightMm,recommendedDpi). It checks in Badger rather than calling Prodigi'sPOST /assets/{id}/validate, which needs the file in Prodigi's library first; for the same file both give about 122 dpi. Used byPodProductServiceImpl.mapandcreateProduct.