Print2medusa

@legenki/print2medusa

Printful → Medusa v2 plugin: sync Store Products, auto-create Printful orders on payment capture, and a Fulfillment Provider for admin shipping options.

MIT licensed.

Requirements

• Node.js ≥ 20
• Medusa 2.18.x (peer dependency)
• Printful store on the Manual order / API platform with a private token (orders, sync_products scopes)

Install

npm install @legenki/print2medusa

Register the plugin and fulfillment provider in medusa-config.ts:

1plugins: [
2  {
3    resolve: "@legenki/print2medusa",
4    options: {
5      apiToken: process.env.PRINTFUL_API_TOKEN,
6      storeId: process.env.PRINTFUL_STORE_ID, // required for account-level tokens
7      // autoSubmitOrders: true,
8      // createOnOrderPlaced: false,
9      // allowPartialOrders: false,
10      // markupPercent: 30,
11      // defaultCurrency: "USD",
12    },
13  },
14],
15modules: [
16  {
17    resolve: "@medusajs/medusa/fulfillment",
18    options: {
19      providers: [
20        {
21          resolve: "@medusajs/medusa/fulfillment-manual",
22          id: "manual",
23        },
24        {
25          resolve: "@legenki/print2medusa/providers/printful-fulfillment",
26          id: "printful",
27          options: {
28            apiToken: process.env.PRINTFUL_API_TOKEN,
29            storeId: process.env.PRINTFUL_STORE_ID,
30          },
31        },
32      ],
33    },
34  },
35],

Then migrate:

npx medusa db:migrate

See examples/basic-store/ for a fuller snippet.

What it does (MVP)

Idempotency

• Re-sync updates existing products via link tables (no duplicates) and upserts variants — price and assortment changes in Printful reach Medusa; manually-added Medusa variants are left untouched.
• Concurrent / re-fired payment events will not create a second Printful order: the order is claimed insert-first via a unique index on printful_order_link.medusa_order_id before the Printful API is called.
• Shipping province is normalized to the 2-letter state_code Printful expects for US/CA.

Admin usage

1. Create products in Printful (Store Products).
2. Open Medusa Admin → Products list → Printful → Sync Now.
3. Configure a location shipping option using the Printful fulfillment provider.
4. Place a test order and capture payment → Printful receives the order.

Local plugin development

1npm install
2npm run build
3npm run dev          # watch + yalc publish
4npm test
5npm run typecheck

In a host Medusa app:

npx medusa plugin:add @legenki/print2medusa

Architecture notes

• Printful is source of truth for products; Medusa holds a copy + links.
• Printful API v1 (https://api.printful.com).
• Long-running sync runs as a Medusa workflow (not a blocking HTTP body only—route awaits the workflow today; can be queued later).
• Webhooks / multi-store / live rates: planned Phase 2.

Options

License

MIT © Andy Legenki