Skip to content

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

  1. 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.
  2. 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: sandbox or live, matching the dashboard the key came from. The dashboard shows the key without its mode, so Badger sends it as sandbox_<key> or live_<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, express or overnight (default standard). 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.
  3. 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.
  4. 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 action managePodProducts 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:

  1. 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.
  2. Choose its Options (such as colour and size) and Print area. Only Prodigi's own combinations are offered.
  3. Choose artwork from the media library. Prodigi fetches it from its public address, so it must be served over HTTPS.
  4. 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.
  5. Save mapping. The same rules as the MCP map action 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.
  6. 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

  1. 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.
  2. 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.
  3. 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_failed and 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): search the Prodigi catalogue, list a product's variants (SKUs, options, print areas, sizes), list this shop's mappings, and the print orders that need someone.
  • managePodProducts (mcp:write): quote Prodigi's prices (items, shipping and VAT apart, for the UK; these are the shop's costs, so they need the write scope), uploadArtwork, make mockups, createProduct (disabled until you enable it), map and unmap a SKU, syncCosts and connectWebhook.

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-config group (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.

  • ProdigiClient over ProdigiHttp (JdkProdigiHttp): Print API v5 calls and rate-limit handling. ProdigiCredentials and ProdigiAccountService read the secrets from prodigi-config and 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 (its README.md gives the source, fetch date and how to update it), into package fulfilment/prodigi/v5 at build time. Where the API and the spec disagree, the API wins: every enum is a plain String (the sandbox sends shipment statuses InProgress and Shipped), and a shipment's items on an order, objects in the spec but item id strings from the API, read as ProdigiShipmentItem, which takes either. ProdigiV5 has the helpers on top (pence, never-null lists, the ids Badger put in an order's metadata). ProdigiSandboxFixturesTest parses 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 (submitOrder and importChannelOrder, on by default) calls ProdigiFulfilmentNotifier.queue, which publishes a ProdigiOrderMessage through ProdigiOrderPublisher onto the queues in ProdigiQueueConfig (the notifier is still the PRODIGI FulfilmentNotifier, but its notifyFulfiller does nothing, so the email fulfilment step never queues twice). The worker's ProdigiOrderListener calls ProdigiOrderSubmitter, which builds the request with ProdigiOrderRequestBuilder, marks the link sending before the call, and looks an unanswered send up with ProdigiOrderFinder (GET /orders?merchantReference=) before giving up. ProdigiOrderLink is versioned, so the worker, a cancellation and a webhook can't overwrite each other's changes. The worker's ProdigiStaleOrderSweepJob runs ProdigiStaleOrderSweeper every 15 minutes (badger.prodigi.stale-sweep-enabled, badger.prodigi.stale-sweep-interval-ms). ProdigiOrderAlerter and ProdigiAttentionService raise and count problems; ProdigiOrderStatuses holds the one list of statuses both go by.
  • Applying Prodigi's state: ProdigiOrderSyncService takes an order as GET /orders/{id} returned it and dispatches (any shipment dispatched, in_transit, shipped or delivered, 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 sets lastRefreshedAt (a targeted update that moves neither updated nor 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 of dispatchClaimedAt): 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 ProdigiOrderRefreshJob runs ProdigiOrderRefresher for every shop with a working key. It reads links in ProdigiOrderStatuses.IN_FLIGHT (pending_submission, submitted, in_production, partially_shipped, shipped, on_hold, paused; never draft, failed, completed, cancelled or Badger's own statuses) through ProdigiOrderLinkService.findQuiet, never refreshed first, then by lastRefreshedAt, 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. ProdigiAttentionService also counts IN_FLIGHT links unchanged for ProdigiOrderStatuses.IN_FLIGHT_STALE_AFTER (14 days).
  • Cancelling: CancelProdigiOrderProcessor checks (validate phase) and CompleteProdigiCancellationProcessor cancels at Prodigi after the refund (core phase), in the cancelOrder and cancelOrderPart pipelines.
  • Receiving: ProdigiWebhookController (rest, in api.yaml under /api/public/v1/fulfilment/webhooks/prodigi/{siteKey}) hands the raw body to ProdigiWebhookService, after ProdigiWebhookVerifier checks the X-Prodigi-Signature header (t=<unix seconds>, v1=<hex>, HMAC-SHA256 of t.body with the webhook secret). It re-reads the order and applies it through ProdigiOrderSyncService; any event whose re-read shows a shipment gone dispatches, not only the shipment events. ProdigiWebhookService.register subscribes the shop's address and stores the secret.
  • Costs: ProdigiCostSyncService, run by the worker's ProdigiCostSyncJob (badger.prodigi.cost-sync-enabled, badger.prodigi.cost-sync-schedule).
  • Admin rules: PodProductService (catalogue search, a SKU's options, quotes, map and unmap, refusing with PodProductException, whose reason is the admin.pod.error.* message key) and PodContentCheck, the blocked-words check.
  • Admin (web-admin, package render/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 by ProductAdminRenderer). The sidebar entry follows NavVisibility.printOnDemand, set by AdminNavService from ProdigiAccountService.isConfigured. Text is under admin.pod.* in messages.properties.
  • MCP: PodTools in the ai module. Its map, unmap and createProduct call PodProductService (map, unmap, createProduct), so the admin and the MCP tools apply one set of rules; PodTools.refusal turns a PodProductException into a tool error with a hint on what to do next.
  • Artwork resolution: PodArtworkChecker fetches the artwork through SafeHttpFetcher, reads its size with ImageDimensions and judges it against the variant's printAreas (widthMm, heightMm, recommendedDpi). It checks in Badger rather than calling Prodigi's POST /assets/{id}/validate, which needs the file in Prodigi's library first; for the same file both give about 122 dpi. Used by PodProductServiceImpl.map and createProduct.