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.

Data Direction Trigger Products, variants, options, prices, images Base → Medusa scheduled job, or on demand Stock levels Base → Medusa scheduled job (more frequent) Orders Medusa → Base Copy to clipboardorder.placed Order status, tracking number Base → Medusa scheduled job

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

Install

1
npm install medusa-baselinker

Add it to Copy to clipboardmedusa-config.ts:

12345678910
module.exports = defineConfig({
  plugins: [
    {
      resolve: "medusa-baselinker",
      options: {
        api_key: process.env.BASE_API_KEY,
      },
    },
  ],
})

Then create the plugin's tables:

1
npx medusa db:migrate

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

Options

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

Option Type Default Description Copy to clipboardapi_key Copy to clipboardstring — Required. API key from the Base.com panel. Copy to clipboardinventory_id Copy to clipboardstring account default Which Base inventory to sync. Copy to clipboardsales_channel_id Copy to clipboardstring first channel Sales channel imported products are linked to. Set it on a store with more than one. Copy to clipboardshipping_profile_id Copy to clipboardstring first profile Shipping profile assigned to imported products. Copy to clipboardorder_status_id Copy to clipboardnumber first status Status given to orders exported to Base. Copy to clipboardcustom_source_id Copy to clipboardnumber — Order source shown in Base for orders from Medusa. Copy to clipboardshipped_status_ids Copy to clipboard(string | number)[] Copy to clipboard[] Base statuses meaning "shipped". Usually unnecessary — an order that acquires a tracking number is treated as shipped anyway. Copy to clipboardmissing_product_strategy Copy to clipboard"draft" | "delete" | "ignore" Copy to clipboard"draft" What happens to a product that disappears from Base. Copy to clipboardmax_missing_ratio Copy to clipboardnumber Copy to clipboard0.2 Largest share of products one sync may withdraw before refusing to act. Copy to clipboardorder_sync_lookback_days Copy to clipboardnumber Copy to clipboard30 How far back the order status sync looks. Copy to clipboardcod_payment_providers Copy to clipboardstring[] Copy to clipboard[] Payment provider ids that mean cash on delivery. Copy to clipboardpayment_method_labels Copy to clipboardRecord<string, string> Copy to clipboard{} Friendly payment names per provider id. Copy to clipboardpickup_point_data_keys Copy to clipboardstring[] Copy to clipboard["target_point", "point_id", "pickup_point_id"] Where to find the pickup point id in a shipping method's data. Copy to clipboardrequests_per_minute Copy to clipboardnumber Copy to clipboard100 Base's own limit. Lower it to leave room for other clients.

Why Copy to clipboardmissing_product_strategy defaults to draft

A product missing from Base is inferred from a paginated listing, and a timed out page, a changed Copy to clipboardinventory_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.

Copy to clipboardmax_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:

Variable Default Runs Copy to clipboardBASE_CATALOG_SYNC_CRON Copy to clipboard0 */6 * * * Full catalog import Copy to clipboardBASE_STOCK_SYNC_CRON Copy to clipboard*/15 * * * * Stock levels only Copy to clipboardBASE_ORDER_SYNC_CRON Copy to clipboard*/10 * * * * Order status and tracking

Set any of them to Copy to clipboardoff 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.

Route Effect Copy to clipboardPOST /admin/base/sync Full catalog import, including stock Copy to clipboardPOST /admin/base/stock Stock levels only Copy to clipboardPOST /admin/base/orders/sync Pull order status and tracking from Base Copy to clipboardPOST /admin/base/orders/:id/export Retry the export of one order

How variants and options are handled

Base has no concept of an option axis. A variant there is a separate product carrying a Copy to clipboardparent_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 Copy to clipboardaddOrder 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 Copy to clipboardexport_error:

12
select medusa_order_id, export_error from base_order_mapping
where export_error is not null;

Fix the cause, then Copy to clipboardPOST /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 Copy to clipboarddelivery_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:

1
pickup_point_data_keys: ["target_point", "point_id", "pickup_point_id"],

The defaults cover the common cases, including the Copy to clipboardtarget_point written by medusa-inpost-fulfillment, so a Paczkomat order works without configuring anything. Dotted paths reach a nested value (Copy to clipboardpoint.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.

12
cod_payment_providers: ["pp_system_default"],
payment_method_labels: { pp_system_default: "Cash on delivery" },

Copy to clipboardcod_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:

Order Copy to clipboardpayment_method_cod Amount recorded as paid Provider listed in Copy to clipboardcod_payment_providers yes 0 Payment captured no the captured amount Payment authorized but not captured no 0

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 Copy to clipboardsetOrderPayment call, because Copy to clipboardaddOrder accepts a Copy to clipboardpaid 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 Copy to clipboardfixtures/, so the mapping layer is fully testable without a Base account:

1
npm test

Two scripts talk to a real account:

123456
npm run recon              # dump API responses into fixtures/
npm run seed               # show what test products would be created
npm run seed -- --setup    # add a second warehouse and price group
npm run seed -- --apply    # create the test products
npm run seed -- --order    # create one test order with a manual parcel
npm run seed -- --cleanup  # remove only what the seed created

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.

Copy to clipboardnpm run seed -- --order attaches a parcel with Copy to clipboardcreatePackageManual, 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