Baselinker

medusa-baselinker

Two-way integration between Medusa v2 and Base.com (formerly BaseLinker).

Base owns the catalog and the warehouse; Medusa is the storefront. Products, prices and stock flow one way, orders flow the other, and shipment status comes back — so a customer sees a tracking number rather than an order stuck at "not fulfilled" forever.

The catalog is never pushed from Medusa to Base, which removes write conflicts entirely.

Install

Add it to medusa-config.ts:

Then create the plugin's tables:

npx medusa db:migrate

Get the API key from the Base.com panel under My account → API.

Options

Only api_key is required. Everything else has a default, and the ones that fall back log a warning naming what they picked.

Why missing_product_strategy defaults to draft

A product missing from Base is inferred from a paginated listing, and a timed out page, a changed inventory_id or a broken pagination loop all look exactly like a mass deletion. A draft product is gone from the storefront for every practical purpose — the Store API filters on published status and the cart rejects variants of unpublished products — but it keeps its handle, its history and its mapping, so a false alarm costs one sync instead of a full reimport.

max_missing_ratio guards both strategies, and a response containing no products at all is refused outright whatever the ratio allows.

Schedules

Job schedules are read at load time, before plugin options exist, so they come from environment variables:

Set any of them to off to disable that job.

Stock runs far more often than the catalog on purpose: it is the figure that goes stale fastest, it is the one that costs a refund when it does, and one request covers the whole inventory.

Manual endpoints

All admin routes, all safe to call repeatedly.

How variants and options are handled

Base has no concept of an option axis. A variant there is a separate product carrying a parent_id, identified by a free-text name.

Where every variant of a product declares the same features — the key/value map Base keeps in a product's text fields — those keys become real Medusa options, so a storefront gets separate Colour and Size selectors. Where the features are missing, inconsistent between variants, or would put two variants on the same combination, the import falls back to a single generated option whose values are the variant names. An honest one-dimensional list beats a broken two-dimensional one.

Features are only visible when a variant is fetched as a product of its own, so the catalog sync makes a second batched pass for them.

Products Base holds without any variants get a single default variant rather than being skipped.

Order export

Base has no idempotency key: calling addOrder twice creates two orders, and the API cannot delete either. The mapping row is therefore written before the call, and an order that already carries a Base id is skipped, so a retry — from a redelivered event, a restarted worker or an operator — is safe.

Failures are recorded on the mapping rather than thrown. A missing variant mapping or a rejected payload will not fix itself on the next attempt, and an exception would only bury it in a subscriber stack trace. Check export_error:

Fix the cause, then POST /admin/base/orders/:id/export.

An order with any unmapped line is not sent at all: a partial order would understate what the warehouse has to pack.

Delivery and pickup points

The shipping method the customer chose is sent as its name and price. Base is not asked which courier that is: mapping a delivery method to one of its 473 couriers is what Base's own automatic actions are for, and that rule belongs where the merchant can edit it rather than in a plugin release.

What the plugin does pass is the pickup point, when the checkout produced one. Base reads the locker or parcel shop from the order's delivery_point_id — the courier's own parcel form has no field for it — so without this an operator has to paste the point id in by hand for every parcel, and no automatic action can create the shipment.

Where that id sits depends on whichever plugin handled the checkout, and carriers agree on no convention, so the keys are configuration:

The defaults cover the common cases, including the target_point written by medusa-inpost-fulfillment, so a Paczkomat order works without configuring anything. Dotted paths reach a nested value (point.id). An order delivered to an address names no point and is unaffected.

Only the id is sent. Base also stores a point name and address, but carrier plugins do not consistently keep them, so those fields stay empty — the id is what a shipment needs.

Payment

Base never takes money. Payment runs through a Medusa provider, and Base is only told the operational consequence: what has been collected, and whether the courier still has to collect the rest.

cod_payment_providers has to be configured if you sell cash on delivery. Medusa has no such concept — it is a manual provider, a custom one, or sometimes a shipping option — so the plugin cannot infer it. The flag decides whether the courier collects money on delivery and what goes on the label: a cash-on-delivery order sent as prepaid ships without collecting anything.

What Base receives:

An authorization is money reserved, not money taken, so it counts as unpaid — the warehouse cares about what has actually arrived.

The amount is sent with a separate setOrderPayment call, because addOrder accepts a paid field and silently ignores it. A payment captured after the order was exported is not pushed to Base; record it there by hand.

What this plugin does not do

• No fulfillment provider. Base's shipping methods are not available in the Medusa checkout; the store's own shipping options are used and their name is passed along with the order.
• No returns or cancellations from Base. Status and tracking come back; a cancellation in Base does not cancel the Medusa order.
• No payment sync after export. The amount paid is sent once, when the order is exported. Capturing a payment later does not update Base.
• No catalog push. Products created in Medusa stay in Medusa.
• Stock is written, not adjusted. Each sync writes the quantity Base reports. This is deliberate: a missed run or a double-applied delta would leave Medusa permanently out of step, whereas writing the value is self-correcting.

Development

The repository carries recorded API responses in fixtures/, so the mapping layer is fully testable without a Base account:

Two scripts talk to a real account:

The seeded products are chosen to hit specific edge cases: a product without variants, variants with and without consistent features, two products sharing a name, diacritics in a title, stock split across warehouses, and a price that differs per price group.

npm run seed -- --order attaches a parcel with createPackageManual, which records a tracking number without contacting any courier, so it cannot produce a billable shipping label.

Commercial support

Setting this up in a live store — mapping your Base statuses, configuring the automatic actions that turn an order into a shipment, or adapting the plugin to how your warehouse actually works — is something we do for a living.

If you would rather not do it yourself, get in touch at digity.studio.

Bug reports and questions about the plugin itself belong in GitHub issues and are free.

Licence

MIT