Packeta

medusa-plugin-packeta

Packeta (Zásilkovna) fulfillment provider for Medusa v2 — pickup points (Z-Point, Z-BOX, external carrier PUDOs), home delivery through Packeta's carrier network across Europe, cash on delivery, labels (PDF/ZPL, Packeta or carrier), push tracking, returns via the claim assistant, plus an admin UI and a storefront widget helper.

Disclaimer: This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or maintained by Packeta s.r.o. / Zásilkovna s.r.o. "Packeta", "Zásilkovna" and their logos are trademarks of their respective owners, used here only to identify the service this plugin integrates with.

npm | Packeta API docs | Medusa Fulfillment Module

Features

• Fulfillment options: packeta-pickup (any Packeta / partner pickup point chosen in the widget), packeta-home-delivery (Packeta home-delivery carrier picked from the shipping country), packeta-return, and — optionally — one option per carrier from Packeta's live carrier feed (packeta-carrier-<id>), so you can price Z-BOX, PPL ParcelShop, InPost, DHL … separately.
• Checkout validation: the selected pickup point is re-validated server-side against Packeta's widget validate endpoint (exists, allowed for your account, currently accepting packets).
• Packets: createPacket on fulfillment with COD, insured value, weight from variant weights, note, earliest delivery date, adult content, dimensions, carrier services, customs declarations for non-EU carriers.
• COD decided automatically from the order's payment provider (pp_system_default by default), overridable per packet in the admin.
• Labels: Packeta PDF (all formats), ZPL (203/300 dpi), external carrier PDF/ZPL, bulk PDF for many packets. Tracking number + label link attached to the Medusa fulfillment.
• Tracking: signed push-tracking webhook (/hooks/packeta) + a polling job fallback; statuses mark the Medusa fulfillment shipped / delivered automatically.
• Cancel packets (and the fulfillment) before hand-over; returns create claim-assistant packets with a drop-off password.
• Admin UI (EN/CS): order-page card with status, destination, COD, labels, refresh, cancel, "Create packet" (split orders into several packets); /packeta page listing all packets with filters, bulk label printing and integration health.
• Storefront helper medusa-plugin-packeta/widget: dependency-free wrapper around Packeta widget v6 + HD widget that returns exactly the data this provider expects.
• Zero runtime dependencies (fetch + node:crypto).

Install

bun add medusa-plugin-packeta   # or npm / yarn / pnpm

Configure

The same options object is passed to the fulfillment provider and to the plugin's packeta module (routes/workflows use the module, the checkout uses the provider). The plugin entry loads the API routes, subscribers, job and admin UI.

1// medusa-config.ts
2const packeta = {
3  api_password: process.env.PACKETA_API_PASSWORD, // 32-hex API password
4  api_key: process.env.PACKETA_API_KEY,           // 16-char API key (feeds, widget)
5  eshop: process.env.PACKETA_ESHOP,               // sender indication (client section → Senders)
6  webhook_signing_key: process.env.PACKETA_WEBHOOK_SIGNING_KEY, // from Packeta support, see Push tracking
7  // optional — see the table below
8  // cod_payment_providers: ["pp_system_default"],
9  // enabled_carriers: ["106", "131", "3060"],
10  // label_format: "A6 on A6",
11}
12
13module.exports = defineConfig({
14  // ...
15  modules: [
16    {
17      resolve: "@medusajs/medusa/fulfillment",
18      options: {
19        providers: [
20          { resolve: "@medusajs/medusa/fulfillment-manual", id: "manual" },
21          { resolve: "medusa-plugin-packeta/providers/packeta", id: "packeta", options: packeta },
22        ],
23      },
24    },
25    { resolve: "medusa-plugin-packeta/modules/packeta", options: packeta },
26  ],
27  plugins: [{ resolve: "medusa-plugin-packeta", options: {} }],
28})

Then run the plugin's migration (creates the packeta_packet table):

npx medusa db:migrate

The provider is registered as packeta_packeta. In the admin: Settings → Locations & Shipping → your location → Fulfillment providers → add Packeta, then create shipping options for the service zone choosing the Packeta fulfillment options (pickup / home delivery / per-carrier). Prices are flat Medusa prices — Packeta has no price API.

Options

Environment

1PACKETA_API_PASSWORD=
2PACKETA_API_KEY=
3PACKETA_ESHOP=
4PACKETA_WEBHOOK_SIGNING_KEY=

Storefront

Packeta pickup points are chosen in Packeta's widget on your storefront. Pass the selection as the shipping method data; the provider validates and normalises it.

1import { pickPoint, pickAddress, pointToShippingMethodData, addressToShippingMethodData } from "medusa-plugin-packeta/widget"
2
3// Pickup point (Z-Point, Z-BOX, partner PUDO). Filter with `vendors` / `country` if you like.
4const point = await pickPoint(process.env.NEXT_PUBLIC_PACKETA_API_KEY!, { language: "cs", country: "cz,sk" })
5if (point) {
6  await sdk.store.cart.addShippingMethod(cart.id, {
7    option_id: pickupShippingOption.id,
8    data: pointToShippingMethodData(point),
9  })
10}
11
12// Home delivery: the address from the cart is enough…
13await sdk.store.cart.addShippingMethod(cart.id, { option_id: homeShippingOption.id, data: {} })
14
15// …or let the customer pick a validated address in Packeta's HD widget (CZ/SK):
16const carrierId = (await fetch(`${MEDUSA_URL}/store/packeta/carriers?country=cz`, { headers }).then((r) => r.json())).home_delivery_carrier_id
17const address = await pickAddress(process.env.NEXT_PUBLIC_PACKETA_API_KEY!, { carrierId, language: "cs" })
18if (address) {
19  await sdk.store.cart.addShippingMethod(cart.id, { option_id: homeShippingOption.id, data: addressToShippingMethodData(address, carrierId) })
20}

The data contract (what pointToShippingMethodData produces) if you drive the widget yourself:

1// Packeta point
2{ "point_id": "79", "point": { "id": "79", "name": "…", "street": "…", "city": "…", "zip": "…", "country": "cz", "group": "zbox", "type": "internal" } }
3// Partner carrier point (InPost, PPL, …)
4{ "carrier_id": "3060", "carrier_pickup_point_id": "BIA10M", "point": { "name": "…", "type": "external", "carrier_id": "3060", "carrier_pickup_point_id": "BIA10M" } }
5// Home delivery with a specific address (optional; the cart address is the default)
6{ "address": { "street": "Vinohradská", "house_number": "1", "city": "Praha", "zip": "12000", "country": "cz" } }

GET /store/packeta/carriers?country=cz returns the public carrier list (id, name, country, pickup_points, disallows_cod, requires_size, max_weight) and home_delivery_carrier_id — handy for widget vendors filters. See docs/storefront-nextjs.md for a Next.js starter walkthrough.

Admin

• Order page → Packeta card: packet barcode, status, destination, COD/value/weight, tracking link, label menu (PDF, ZPL, carrier PDF/ZPL), refresh, cancel, return password. Create packet opens a drawer to choose items (split into several packets), COD, weight, note, earliest delivery date, adult content and dimensions.
• Packeta page (sidebar): all packets with search/filters, bulk Print labels, bulk Refresh, and health badges (API password, feed, webhook).
• Fulfilling an order the native way (Fulfill items) also creates the packet — the plugin mirrors it into packeta_packet and attaches the tracking label.
• The admin UI is in English and Czech (follows the browser language).

Admin API

How it works

1. Checkout — validateFulfillmentData receives the widget selection, checks it with Packeta's validate endpoint (pickup) or resolves the home-delivery carrier for the shipping country, and stores a normalised { kind, point_id | carrier_id + carrier_pickup_point_id, point | address } on the shipping method.
2. order.placed — a subscriber looks at the payment provider; COD orders get metadata.packeta_cod = true (the fulfillment provider cannot see payments itself).
3. Fulfillment — createFulfillment maps order + shipping data to Packeta createPacket (recipient, destination, value, weight, COD, note, size, customs). The packet id/barcode land in fulfillment.data; a subscriber mirrors them into packeta_packet and attaches the tracking label to the fulfillment.
4. Tracking — Packeta pushes status events to /hooks/packeta (HMAC-SHA256 signed, deduplicated by event id). arrived/departed/… mark the fulfillment shipped, delivered marks it delivered. The polling job does the same for stores without push tracking.
5. Cancel — before hand-over, cancelPacket at Packeta and the fulfillment is cancelled in Medusa. Afterwards Packeta refuses (CancelNotAllowedFault) and so does the plugin.
6. Returns — a return shipping option using packeta-return creates a claim-assistant packet (createPacketClaimWithPassword); the customer drops it at any pickup point with the password shown in the admin (Packeta e-mails it too when the return has an e-mail).

Push tracking (webhook)

Packeta enables webhooks per account: e-mail integrations@packeta.com with your HTTPS URL

https://<your-backend>/hooks/packeta

and they issue a signing key → webhook_signing_key. Requests are verified with HMAC-SHA256(key, "{X-Webhook-Timestamp}.{rawBody}") in constant time and the timestamp must be within webhook_tolerance_s (5 min) of the server clock — unsigned, tampered or replayed requests get 401, unknown packets 200 (so Packeta stops retrying). Events are deduplicated by X-Webhook-Event-Id, and a late/replayed event can never move a delivered / returned / cancelled packet backwards. Until the key is configured, the polling job (every 30 min by default, poll_status_cron) keeps statuses fresh. allow_unsigned_webhook is for local development only and is ignored when NODE_ENV=production.

Cash on delivery

COD is applied when the order's payment provider is in cod_payment_providers (default: Medusa's manual pp_system_default): order.metadata.packeta_cod is set to true at order.placed. The admin "Create packet" drawer shows the detected state and lets you override amount/off. Carriers with disallowsCod reject COD packets with a clear error.

Split shipments (several packets per order, from the drawer or native partial fulfillments): the customer pays the order once — the first packet carries the full COD, after which the flag flips to "collected" (with packeta_cod_barcode) and every later packet is created with COD 0 unless you pass cod_amount explicitly. Each packet is insured for the value of the items it carries (plus shipping on the first one) and follow-up packets get a <order>-2, <order>-3 reference.

Customs (non-EU)

For carriers flagged customsDeclarations in the feed the plugin sends attributes (ead, deliveryCost, invoiceNumber, invoiceIssueDate) and items built from the order lines (variant/product hs_code, origin_country, title, value, units, weight). Configure customs.ead (carrier default), fallbacks (default_hs_code, default_origin_country) and pass per-packet extras (invoiceFile, eadFile, mrn, customs_items) via additional_data.customs when creating the fulfillment programmatically. See Packeta's customs documentation.

Storefront-agnostic notes

• Provider id: packeta_packeta; fulfillment option ids: packeta-pickup, packeta-home-delivery, packeta-return, packeta-carrier-<id>.
• Weight: Medusa variant weight is treated as grams.
• Amounts: Medusa v2 major units map 1:1 to Packeta value/cod. Currencies other than CZK/EUR/HUF/PLN/RON fall back to the destination country's currency.
• Phone numbers must be in Packeta's accepted formats (E.164 recommended).

Development

1bun install
2bun run check              # format + lint + typecheck + unit tests
3bun run build              # medusa plugin:build → .medusa/server
4bun run test:integration   # boots a real Medusa app against a mocked Packeta API (needs Postgres: DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD)

Live smoke against your Packeta account (creates and cancels a real, free packet — use a test sender):

1PACKETA_API_PASSWORD=… PACKETA_API_KEY=… PACKETA_ESHOP=… bun run smoke
2bun run smoke carriers cz          # feed
3bun run smoke validate 79          # widget validate endpoint
4bun run smoke label <packetId>     # write label PDF

Try it inside a Medusa app without publishing: scripts/dev-install.sh <path-to-medusa-app> builds, packs and installs the tarball, then follow the config above.

License

MIT

This project is an independent, unofficial integration and is not affiliated with or endorsed by Packeta s.r.o. / Zásilkovna s.r.o. All Packeta and Zásilkovna trademarks and logos are the property of their respective owners.