InPost

medusa-inpost-fulfillment

InPost fulfillment provider plugin for MedusaJS v2. Integrates with the InPost ShipX API to support Paczkomat locker and courier delivery.

🧪 Beta testers wanted



This plugin has been tested thoroughly against the InPost sandbox, but not yet end-to-end against a production InPost account. If you have production InPost ShipX credentials and are using Medusa v2, I'd love your help validating real locker and courier shipments.



What you'd get:



Reach out by opening a GitHub issue or emailing the maintainer. Bug reports from production use are especially welcome.

• Free setup assistance
• Priority bug fixes

Features

• Paczkomat locker delivery (Copy to clipboardinpost_locker_standard) — ships to a selected InPost locker machine
• Courier delivery (Copy to clipboardinpost_courier_standard) — ships to the receiver's address with automatic dispatch order creation
• Automatic offer selection and purchase (for prepaid accounts)
• Shipment label retrieval (PDF/ZPL)
• Shipment cancellation
• Polish postal code normalization (5 digits to XX-XXX format)
• Parcel dimensions aggregated from cart item variants

Prerequisites

• MedusaJS v2 (Copy to clipboard@medusajs/framework ^2.5.0)
• Node.js >= 20
• InPost ShipX API credentials (register here)

Installation

1
npm install medusa-inpost-fulfillment

Configuration

Add the plugin to your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
import { defineConfig } from "@medusajs/framework/utils";

export default defineConfig({
  // ...
  plugins: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          // default provider
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
          {
            resolve: "medusa-inpost-fulfillment/providers/inpost",
            id: "inpost",
            options: {
              // Required
              apiToken: process.env.INPOST_API_TOKEN,

Environment variables

Variable Description Copy to clipboardINPOST_API_TOKEN Your InPost ShipX API token Copy to clipboardINPOST_ORGANIZATION_ID Your InPost organization ID

Shipping options

After installing the plugin, create shipping options in the Medusa admin that use the InPost fulfillment provider. The plugin exposes two services:

Service ID Description Copy to clipboardinpost_locker_standard Paczkomat locker delivery Copy to clipboardinpost_courier_standard Courier home delivery

Where to find your shipments

InPost uses different apps for locker and courier shipments:

• Locker (Paczkomat) shipments — visible in Manager Paczek (sandbox: sandbox-manager.paczkomaty.pl)
• Courier shipments — visible in WebTrucker at kurier.inpost.pl under "Przesyłki do nadania" (Shipments to send), and later under "Monitoring" once InPost processes them

Note on sandbox for courier shipments: WebTrucker has no sandbox equivalent, so courier shipments created in sandbox will not appear in any UI. In sandbox, a correctly created courier shipment will simply reach status Copy to clipboardconfirmed via the API — that is the sandbox success criterion. Only production courier shipments are visible in WebTrucker.

Storefront integration

Locker delivery

For Paczkomat locker delivery, the storefront must pass Copy to clipboardtarget_point (the Paczkomat machine ID) when adding a shipping method to the cart:

123456
await sdk.store.cart.addShippingMethod(cartId, {
  option_id: lockerShippingOptionId,
  data: {
    target_point: "WAW123", // Paczkomat machine ID
  },
});

You can use the InPost Geowidget to let customers pick a Paczkomat on a map.

Courier delivery

For courier delivery, no additional data is needed — the receiver address is taken from the cart's shipping address:

123
await sdk.store.cart.addShippingMethod(cartId, {
  option_id: courierShippingOptionId,
});

Parcel dimensions

For courier shipments, the plugin aggregates parcel dimensions from cart item variants (the Copy to clipboardweight, Copy to clipboardlength, Copy to clipboardheight, and Copy to clipboardwidth fields on product variants). If no dimensions are set, defaults are used (200x200x100mm, 1kg).

For locker shipments, a parcel template (Copy to clipboardsmall, Copy to clipboardmedium, or Copy to clipboardlarge) is used instead, configurable via the Copy to clipboarddefaultParcelTemplate option or per-shipment via Copy to clipboardparcel_template in fulfillment data.

How it works

Fulfillment flow

1. Create shipment — sends parcel, receiver, and sender data to InPost ShipX API
2. Offer handling — for prepaid accounts, the plugin polls for offers, selects the first available one, and purchases it
3. Dispatch order (courier only) — creates a dispatch order to schedule courier pickup from the sender's address
4. Return data — stores Copy to clipboardshipment_id, Copy to clipboardtracking_number, and Copy to clipboarddispatch_order_id in the fulfillment data

Cancellation

When a fulfillment is cancelled in Medusa, the plugin attempts to cancel the corresponding shipment in InPost.

Important: InPost only allows cancelling shipments that are still in Copy to clipboardcreated or Copy to clipboardoffers_prepared status. Once a shipment has been confirmed (label purchased/dispatch order issued), the InPost API will reject the cancel request. In that case, the plugin logs a warning and lets Medusa mark the fulfillment cancelled locally only — the physical shipment must be cancelled manually in InPost Manager (for locker shipments) or WebTrucker (for courier shipments).

Labels

The plugin supports retrieving shipment labels as PDF documents through Medusa's fulfillment documents API.

Returns

Return shipments are not created automatically — they should be created manually in InPost Manager, as Medusa's return flow does not provide sufficient data (e.g., target locker for locker returns).

Options reference

Option Type Required Default Description Copy to clipboardapiToken Copy to clipboardstring Yes — InPost ShipX API token Copy to clipboardorganizationId Copy to clipboardstring Yes — InPost organization ID Copy to clipboardsandbox Copy to clipboardboolean No Copy to clipboardfalse Use sandbox API environment Copy to clipboarddefaultParcelTemplate Copy to clipboard"small" | "medium" | "large" No Copy to clipboard"small" Default parcel template for locker shipments Copy to clipboardsender Copy to clipboardobject For courier — Sender details (required for courier shipments) Copy to clipboardsender.company_name Copy to clipboardstring No — Sender company name Copy to clipboardsender.first_name Copy to clipboardstring No — Sender first name Copy to clipboardsender.last_name Copy to clipboardstring No — Sender last name Copy to clipboardsender.email Copy to clipboardstring Yes — Sender email Copy to clipboardsender.phone Copy to clipboardstring Yes — Sender phone number Copy to clipboardsender.address Copy to clipboardobject Yes — Sender address

License

MIT