I
Inpost
Провайдер фулфилмента InPost от Koda Plus для Medusa на базе InPost ShipX API. Поддерживает постаматы Paczkomat и курьерскую доставку InPost с наложенным платежом и предлагает четыре опции. Отправления создаются только по плану, который вы сначала просматриваете (по умолчанию выключено).
InPost by Koda Plus
Ship with InPost from Medusa: Paczkomat parcel lockers and the InPost courier, both also with cash on delivery, on InPost's ShipX API. A fulfillment provider with four shipping options checks the chosen locker at checkout and records it on every fulfillment. The plugin turns that fulfillment into a ShipX shipment from a plan a person reads first, prints the label through the backend, follows the parcel to the locker by webhook with a fallback status pass, and tells the rest of your store about it through events.
Writes are off by default. Without them the plugin already works: fulfillments record the locker and the service, plans show exactly what would be sent, labels and statuses of existing shipments are read. Creating, paying, ordering a courier and canceling in InPost happen only when you allow the writer in the options and arm it in the admin, and then either by a button on the plan or, if you choose, automatically.
Live demo: Medusa admin medusa.koda.plus/app/inpost, signed in to a public demo account by the link itself. The demo runs the plugin in demo mode: sample shipments built from the demo store's own orders, simulated labels, statuses and courier pickups, and zero requests to ShipX.
What it does
- Checkout: four shipping options, Paczkomat, Paczkomat with cash on delivery, courier, courier with cash on delivery. A Paczkomat option needs a locker code of the right shape that exists in InPost's list; a courier option needs a Polish address with a building number; cash on delivery needs a cart in PLN. The storefront picks the locker with InPost's Geowidget or with the plugin's own locker search.
- Fulfillment: creating a fulfillment in Medusa records the option, the locker, the parcel size and the cash on delivery amount (the order's gross total, to the grosz). Nothing is sent to InPost at this moment, so a fulfillment works even when InPost is down.
- Panel in the admin, in the lists a warehouse works with: to create, waiting for pickup, in transit, in the locker, delivered, problems and returns (plus skipped and canceled), each shipment next to its order, with its locker or address, cash on delivery, status and tracking number.
- Plan, then create: the plan of a shipment shows the receiver (read from the order at that moment), the locker or the address, the size and the weight, cash on delivery with its insurance, the reference, the sending method, the sender and the exact ShipX request. Create sends that plan, once.
- Prepaid accounts: when InPost prepares offers instead of buying a shipment (), the plugin buys the offer of the shipment's service, as the plan announced, as soon as the webhook or the status pass sees it (with the shipment writer armed; Pay the offer does it by hand). Until then the Panel shows the shipment as waiting for payment.
- Courier pickups for shipments sent with the method: one dispatch order for all confirmed shipments, from the sender's address.
- Labels: PDF in A6 or A4 through the backend, so the ShipX token never reaches the browser.
- Tracking: statuses by webhook, with a status pass every 15 minutes as the fallback; the tracking link on inpost.pl; the names of all 53 ShipX statuses in English and Polish.
- Medusa follows InPost (optional writer): the fulfillment is marked shipped with the tracking number and link when InPost has the parcel, and delivered when it is delivered.
- Order widget on the order page: the customer's choice with the locker and a map link, each shipment with its status, tracking, cash on delivery, label, plan, actions and history.
- Locker search in the admin (to fix a wrong locker before sending) and for the storefront ().
- Setup guide and Settings in the admin: the InPost account and the webhook, the sender with the default parcel and label, the writers, the history.
Features
- The right ShipX hosts: and, with , .
- Exact cash on delivery: amounts are integer grosze end to end and go to ShipX as decimals with two places; the insurance equals the amount, as InPost requires for couriers. A cart in another currency cannot choose a cash on delivery option.
- Parcel sizes A (small, 8 x 38 x 64 cm), B (medium, 19 x 38 x 64 cm) and C (large, 41 x 38 x 64 cm): a default in the options or in Settings, changeable per shipment before it is sent. Lockers take one parcel up to 25 kg, couriers up to 30 kg; the weight comes from the variants, or .
- Validation before InPost sees it: locker codes, Polish phone numbers of nine digits ( and spaces removed), e-mail, the street split from the building and flat number, postal codes like 00-950, the reference of 3 to 100 characters. Every problem is named in the plan with what to fix.
- Created exactly once: one row per fulfillment (unique index), an atomic claim with a lease before the request, and an unclear answer (a timeout, a 5xx) is never retried blindly: the shipment is looked up in ShipX by its receiver and reference first, and adopted when it exists.
- No second parcel for orders shipped elsewhere: names the order metadata keys another system writes when it ships an order; such orders are skipped, and a key holding is tracked instead.
- Webhook with a fallback: the webhook only says which shipment changed; the plugin reads the shipment from ShipX itself. Every change is applied once (compare and set), whether the webhook or the status pass sees it first.
- Events other plugins build on: , , , a documented payload without personal data.
- Never breaks the boot: missing or broken options are listed in the admin; without a token the plugin records fulfillments and says "Not configured"; demo mode runs only with .
- Demo mode from the store's own orders, through the same plans, writers and events, with zero requests to InPost.
- Admin in English and Polish, with "Copy prompt" for an AI agent and help on the Koda Plus Discord.
Requirements
- Medusa 2.12 or newer and Node.js 20+ (see Compatibility).
- An InPost business account in InPost Manager with ShipX API access: the API token and the organization id. For tests, an account in the ShipX sandbox.
- Shipping to Poland. Cash on delivery needs orders in PLN and a payment method that does not take the money online (Medusa's manual provider, or one for payment on delivery, listed in ).
- Only one InPost plugin per store. Do not install this plugin next to another InPost fulfillment plugin for Medusa: both would answer the same orders and could send two parcels for one. Remove the other one first. This plugin keeps its data in its own tables (, , ) and never reads or writes the tables of another plugin.
Installation
Yarn and pnpm work the same way: or .
Configuration
The plugin is registered twice with the same options object: as a plugin (its data module, the admin page, the routes, the jobs and subscribers) and as a provider of Medusa's fulfillment module (the shipping options and the checkout checks). Keep the object in one constant:
Keep the id : the provider is then , the id the earlier InPost providers of Koda Plus used, so shipping options created with them keep working. If your already has the fulfillment module, add the provider to its instead of a second entry.
An app that carries the plugin's code in its own instead of the package registers the same two entries by path: in , and among the fulfillment providers.
Set the variables in :
Run the migrations, then open InPost in the admin sidebar:
npx medusa db:migrateThen create the shipping options: Settings, Locations and Shipping, the shipping zone of your location, Create option, the InPost provider and one of its four fulfillment options (ids , , , ). The price is the shipping option's own: the provider does not calculate prices.
Options
Every option is optional. Numbers and booleans may come as strings from environment variables, lists as comma separated strings; broken values fall back to the defaults and are listed in the admin. Missing options never break the boot.
Connection:
- (default none): the ShipX API token from InPost Manager (My account, API). Only in the header of the server's requests; masked in every log, error and admin screen. The Geowidget token of the same page is another, public token: ShipX answers it with 401.
- (default none): the organization id shown next to the token, digits only.
- (default ): the ShipX sandbox instead of production, for the API, the points and the Geowidget.
- (default ): sample shipments built from the store's orders; nothing is sent to InPost. Only turns it on: a missing token never does, so a variable lost on production cannot turn real fulfillments into sample rows. Without a token the plugin records fulfillments, says "Not configured" in the admin and sends nothing.
Writes:
- (default ; in demo mode , acting on the simulation only): allows the ShipX writes: create a shipment, buy the offer of a prepaid account, order a courier pickup, cancel a shipment ShipX still allows to cancel. The admin cannot arm it while this is not .
- (default ; in demo mode , simulated): allows marking Medusa fulfillments shipped and delivered.
- (default ): with the shipment writer armed, create the shipment as soon as its fulfillment is created, from its plan, without a click, and let the status pass order the courier pickup of confirmed shipments. Plans with problems wait for a person either way.
- (default , 1 to 720): the status pass creates only fulfillments recorded after the shipment writer was armed and within these hours. A backlog (fulfillments shipped by hand while the writer was off) is never turned into new, paid labels.
- (default ): the payment providers that mean "pay at the door". When an order has a payment by any other provider (a card, BLIK, Przelewy24), its cash on delivery plan stops with : the buyer never pays twice.
Shipments:
- (default ): , or (or , , ). A value saved in Settings wins over the option.
- (default ): or . Courier labels exist only as A6. Settings may override it.
- (default none): . Without it InPost uses your organization's data from InPost Manager, which InPost recommends. The sender goes into a shipment only with an e-mail and a phone; a courier pickup needs the full address. Settings may override it.
- (default: your account's own): ShipX per kind, like . Values: , , , , , , .
- (default none): the locker you drop parcels off at, sent with the sending method.
- (default ): the shipment reference, with , and . The second parcel of an order gets , the third . ShipX takes 3 to 100 characters.
- (default ): the unit of variant weights in Medusa, or .
- (default ): the parcel weight when the variants have none (the plan says it is estimated).
- (default none): order metadata keys that mean "shipped outside Medusa". An order carrying any of them gets no shipment; when the key holds (or ), that ShipX shipment is tracked instead. A store whose order management system records its InPost shipments under sets .
Checkout:
- (default ): check at checkout that the chosen locker exists, in InPost's public points list (cached; when the list does not answer, the checkout goes on).
Tracking and limits:
- (default none, so no webhook): the secret part of the webhook URL, at least 24 lowercase letters and digits (). A value of another shape keeps the webhook closed and is listed in the admin.
- (default ): the status pass every 15 minutes, the fallback of the webhook.
- (default , from 1 to 365): shipments older than this are no longer read.
- (default , at most 600): the plugin's own limit towards ShipX.
- (default , from 3000 to 120000): one ShipX request.
- (default ): searches one IP may send to per minute.
Presentation:
- (default none): stores running the integration, shown in the admin ("Running in stores built by Koda Plus"): , texts plain or . marks a store that starts on Medusa soon: a "Soon" badge, no link, optional. Entries without a name, or live entries without an https address, are dropped.
Storefront
When the customer picks a Paczkomat option, show InPost's Geowidget (v5) and send the chosen point with the shipping method. Generate the Geowidget token in InPost Manager (My account, API, Geowidget) for your storefront's domain:
With , load the sandbox Geowidget from with a sandbox token.
The shipping method data fields:
- (required for the Paczkomat options): the locker code. and are accepted as well.
- (optional): what the storefront shows, kept on the order.
- (optional): , shown in the admin and the order widget.
- (optional): , or , when the storefront knows better than the default.
The courier options need no data: the order's shipping address is the delivery address. At checkout the provider answers a Paczkomat option without a valid locker, a locker InPost does not list, a courier option without a full Polish address and cash on delivery outside PLN with a 400 and a message the storefront can show.
The provider stores the method data in one shape, with the earlier fields first (, , , , ), then , , and . The shipping options' own data carries , , , , and the earlier , so a storefront can tell a locker option from a courier one.
Store API
finds parcel lockers for a storefront without the Geowidget. Like every route it needs the publishable API key ().
- : a locker code (), a postal code (, nearest first) or a city ().
- and instead of : the nearest lockers to a place in Poland.
- : only points that take card payments, for the cash on delivery options.
- : every kind of point, not only parcel lockers.
- (default 10, at most 25).
The answer is . Each point has , , , , (, , , , , , ), (, ), , , , and in metres when the search had a place. Store the chosen one as , , .
Only InPost's public points data is returned. Answers are cached for ten minutes on the server and may be cached for five in the browser. Each client address (as Medusa resolves it behind your proxy) may send searches a minute; above that the route answers 429 with . A search that is neither a code, a postal code, a city nor a place in Poland answers 400; when InPost's list does not answer, 502. Demo mode answers with the demo lockers.
Webhook
ShipX calls . Paste that URL in InPost Manager (My account, API, webhook); Settings in the admin shows it ready to copy. InPost checks the URL with a GET before saving it.
- The secret in the path is the only key. It is compared in constant time; a wrong secret, or no in the options, answers 404, as if the route did not exist. ShipX signs nothing, so the plugin trusts nothing else either.
- The body is a doorbell. A delivery is answered 200 at once; then the plugin reads the named shipment from ShipX with its own token and applies what ShipX says. A forged call changes nothing.
- Once. Each delivery is recorded under its own key (event, shipment, status, time), so a repeated delivery stops there; a status already applied by the status pass is not applied again, and its events are not emitted again.
- Events handled: , and ; anything else is answered 200 and ignored. Deliveries for another organization and, in demo mode, all deliveries are ignored.
- InPost sends webhooks from , if your firewall allows only known addresses.
- Medusa puts no authentication on , so no middleware is needed.
The fallback: the job runs every 15 minutes (minutes 7, 22, 37 and 52). It reads open shipments again (each at most every 25 minutes, younger than ), looks up creates without a clear answer, buys prepaid offers and catches up the fulfillment status writer. A store without the webhook still gets every status, only later.
Events
All three carry the same payload, . The shape is a contract: fields and events may be added, never changed.
- : once per shipment, when ShipX accepts it, or when the plugin adopts a shipment it found after an unclear answer.
- : once per change of the ShipX status, from the webhook or the status pass.
- : once, when the status becomes , after its .
The receiver's name, phone, e-mail and address are never in an event. A subscriber that writes to the outside world should skip :
With the fulfillment status writer armed, Medusa's own follows when InPost has the parcel, so your "order shipped" e-mail carries the InPost tracking link.
Setup in brief
The admin has the full guide (InPost, Setup guide, or ), each step with its state from your store.
- Get the ShipX token and the organization id in InPost Manager (manager.paczkomaty.pl): complete the company and invoice data, then My account, API.
- Try the sandbox first (sandbox-manager.paczkomaty.pl) with . Sandbox courier shipments reach but never show in WebTrucker, and public tracking does not work there.
- Install the plugin and its provider as above, with the same options object and the id .
- Run .
- Create the shipping options for the four fulfillment options and set their prices.
- Let the storefront send the chosen locker (Geowidget or ) as .
- Connect the webhook: set , restart, paste the URL in InPost Manager.
- Settings: the sender (or InPost's organization data), the default parcel size and the label size.
- Read a plan, then arm the shipment writer: fulfill a test order, open its plan, read every line, allow , arm it in Settings and create the first shipment. Turn on later if you want shipments without a click.
- Optionally arm the fulfillment status writer, so Medusa marks fulfillments shipped and delivered.
- Go live: the production token, the sandbox off, the go-live checklist.
Write safety
- Two switches per writer. The option (, ) is the hard one: wins and the admin cannot override it. The switch in Settings is the runtime one, stored with who flipped it and when. Demo and live toggles are separate.
- Plan first. A person creates a shipment from its plan and sends the plan's hash with the click; when the order, the settings or the shipment changed since the plan was read, the create is refused and the new plan is shown. A plan with problems sends nothing.
- Auto or button. With , an armed writer creates the shipment when its fulfillment is created, from a plan without problems, and the status pass orders the courier pickups; otherwise every shipment and every pickup waits for its button. The pass never takes a backlog (), and a fulfillment Medusa already marks shipped or delivered gets no shipment.
- Cash on delivery once per order. The amount is what is still due (the order total minus what was captured), on the first live cash on delivery parcel of the order; further parcels of the same order go without it. An order paid online () gets no cash on delivery at all.
- One shipment per fulfillment: a unique row before anything goes out, an atomic claim with a lease, and the state after an unclear answer, resolved by a lookup in ShipX (by the receiver and the reference) before anything is sent again. Only a lookup a quarter of an hour later that still finds nothing lets a person try again.
- Cancel only while ShipX allows it: the status is read first, and only , and can be canceled. Later, the admin says to cancel in InPost Manager (lockers) or WebTrucker (courier). Shipments the plugin did not create (linked, or found under ) are only tracked, never canceled or paid.
- Prepaid offers once: one purchase per shipment at a time (an atomic claim), whoever asks first, the webhook, the status pass or a person.
- One courier pickup per shipment: shipments are claimed before the dispatch order, so none is in two pickups.
- Medusa marks once: shipped and delivered are claimed on the row before Medusa's flow runs and released with the error if it fails; a fulfillment a person already marked is only noted.
Security and data
- The token stays on the server: only in the header towards the ShipX host of the configured environment; masked in logs, errors, the history and the admin, which only knows whether it is set. Labels are fetched by the backend and streamed to the admin.
- The webhook trusts only its secret, compared in constant time, and re-reads every shipment from ShipX.
- Personal data stays where it lives: the receiver's name, phone, e-mail and address are read from the order when a plan is built and sent to ShipX only when a shipment is created. The plugin's tables keep the order and fulfillment ids, the option, the locker (public data), the parcel, the cash on delivery amount, the reference and the statuses; problems name what is wrong, never the value. Events carry no personal data.
- Rate limited towards ShipX (), with retries only for reads (network errors, 5xx, 429 with ); writes are sent once.
- History: status passes, webhook deliveries, actions and statuses are kept for 120 days.
- Admin routes sit behind Medusa's admin authentication. Writes to take a JSON body or the header and answer 415 otherwise: Medusa's session cookie is in production, so a form on another site could otherwise post with it (shipments, offers and pickups cost money). The plugin's admin sends both.
- Shopper metadata is not state. A shopper may not set keys or the keys of on a cart or the account through the Store API (400 ); those are written by the store's own systems through the admin API.
- Reads do not write: routes only read; demo samples are built by and by the status pass.
- serves public locker data only, limited per client address as Medusa resolves it behind your proxy (), never by a header the client sends.
- Errors: unexpected server errors answer a plain sentence; the details stay in the server log, masked.
What this plugin does not do (yet)
- It does not create returns yet: self-service returns through InPost's Returns API (Szybkie Zwroty) and return labels are planned; until then use InPost Manager. A parcel returned to the sender shows under Problems and returns.
- It does not calculate shipping prices from InPost's price list: the shipping options' own prices apply.
- It does not send several parcels in one shipment: one shipment carries one parcel (split the items into more fulfillments for more parcels).
- It does not change a shipment after it is sent (the locker, the size, the receiver): InPost allows that only in InPost Manager.
- It uses two ShipX services, and : no express, weekend, Allegro or international services.
- It does not notify the customer itself: Medusa's and the plugin's events let your e-mail plugin do that.
Admin API
Every route is behind Medusa's admin authentication. Writes answer 409 while the shipment writer is not allowed and armed.
- : the status (mode, configuration, counts, writers, settings, webhook, last pass). No call to ShipX.
- : the Panel lists.
- , : a shipment with its history; its plan with the hash.
- : creates the shipment from the plan that was read.
- , , , : cancel while ShipX allows it, buy the prepaid offer, read the status, look up an unclear create.
- , , , , : edits before sending, try a failed create again, mark as handled outside, link a shipment created elsewhere.
- : the label PDF.
- : one courier pickup for the confirmed shipments.
- : the order widget.
- : the locker search.
- : the sender, the default parcel size and the label size of the current mode.
- : arms or disarms a writer.
- : a status pass now (202). : checks the token and the organization.
- : the history. : demo mode only, builds the sample shipments once. : demo mode only, starts the simulation over.
- , , : the koda.integration/1 contract, see below.
Works with Koda Plus hosts
An app that shows every Koda Plus plugin in one place (like medusa.koda.plus) reads InPost through the shared contract and never needs to know its tables:
- : the manifest (mode, configuration, writers armed, widgets).
- (or , up to 50): one line per order, the worst parcel speaking (not created, a delivery problem or a return is red; to ship, an offer to pay or a canceled shipment with an open fulfillment is orange; on the way is blue; delivered is green), with the facts (Paczkomat or courier, tracking number and link) and (cash on delivery with the amount). Facts come from the plugin's rows and the shipping method data the provider validated, never from order metadata.
- : counters , , , , each with a link to its filtered list ().
- The order card registers as for the zone ; a host that claims the zone shows it as a tab () and Medusa's own spot stays empty. Without a host nothing changes.
- The page opens on deep links: , .
Public API
What other code may import: , (the module, its options and event types), (the fulfillment provider) and . Type declarations ship with the package. Every other path is internal and may change in any release.
Uninstall
- Move the shipping options off the InPost provider () or delete them, so no new fulfillment uses it.
- Remove the webhook URL in InPost Manager (My account, API, Webhook).
- Remove the plugin and the provider from and the package from .
- The tables , and stay with your data; drop them by hand when you no longer need the history.
Compatibility
Medusa 2.12 to 2.21 (peer range ) and Node.js 20+. The release of each version runs the smoke test on a fresh Medusa 2.12.6 and 2.21.2 app: migrations, build, start and the admin pages. Developing the plugin needs Node.js 22.6+ (the tests run the TypeScript sources directly).
Workflows
The same rules as the admin: creating needs the shipment writer allowed and armed.
Demo mode
builds 16 sample shipments from the store's newest orders: three to create (one without a locker), two waiting for pickup, one waiting for the payment of a prepaid offer, two in transit, two in the locker (one after a pickup reminder), three delivered, one not collected in time, one returned to the sender, and one skipped because another system shipped the order. The lockers are invented (KSP01M to KSP05G), tracking numbers start with 99 and never link to inpost.pl, labels say they are simulated. Arm the shipment writer in Settings and create a shipment from its plan: it moves along by itself, from the label to the locker. Demo rows never meet real ones, Medusa's fulfillments are never touched, and nothing is sent to InPost.
Development
covers the plan and the exact ShipX request for each option, cash on delivery in grosze, the address and locker parsing, the options and references, the ShipX client (hosts, retries of reads only, errors, masking), the points search, the SQL of the claims and the compare and set of statuses, the flows end to end against a fake Medusa and a scripted ShipX (create once, unclear answers, prepaid offers, pickups, cancel rules, the fulfillment status writer), the webhook, the demo generator and the house rules of the copy. With it also runs the migration (twice) and every SQL statement of the store on a real Postgres, in a scratch schema it drops afterwards. What the plugin relies on from InPost's documentation is in docs/shipx-api-notes.md. To try the plugin in a Medusa app, run here, then in the app.
Commercial support
Built and maintained by Koda Plus, a Medusa agency from Poland, next to our Fakturownia, BaseLinker, Allegro, OLX, Subiekt nexo and Stripe integrations. Need a hand with shipping or a Medusa store? Write to kontakt@koda.plus.
Trademarks
InPost, Paczkomat and the InPost logo are trademarks of InPost, used here only to identify the service this plugin connects to. This is an independent integration built on InPost's public ShipX API, not affiliated with or endorsed by InPost.
License
MIT, see LICENSE.
Changelog
0.2.0 (first npm release)
Demo mode only with ; cash on delivery collected once per order and never after an online payment; the status pass picks open shipments in the database; no backlog for ; writes only from the admin or a server (JSON or ); reads never write; the koda.integration/1 contract for Koda Plus hosts with an embeddable order card; type declarations. Full list in CHANGELOG.md.