Fulfillment nshift

@solteq-excom/medusa-fulfillment-nshift

nShift Checkout fulfillment provider for Medusa v2.

Brings nShift's delivery options into a Medusa storefront: real carrier options, real prices for the customer's address and basket, and a partial shipment created in nShift when the order is fulfilled.

• Dynamic delivery options — the options an admin can attach to a shipping option come straight from your nShift Checkout configuration.
• Calculated pricing — prices are fetched per cart, using the receiver address, package weight/volume and basket value, so nShift price rules (free shipping thresholds, weight bands, per-country pricing) apply.
• Pickup points, time slots and addons — selected at checkout, validated against nShift, and forwarded to the shipment.
• Partial shipments — created on fulfillment, deleted again when the fulfillment is cancelled.
• Fails soft — if nShift is unreachable or does not offer an option for a cart, that option is simply reported as unavailable. Checkout keeps working.
• Token and session handling — OAuth2 tokens are cached and refreshed; one nShift session is reused across all the options of a cart.

Requirements

• Medusa >= 2.13.3
• Node >= 20
• An active nShift Checkout agreement

Installation

nShift account setup

1. Log in to the nShift Portal.
2. Settings → API Configuration → Clients → Add. Give the client the Public checkout API scope and copy the Client ID and Client Secret (the secret is only shown once).
3. Connections — copy the Connection ID you want Medusa to use.
4. Configure the Checkout configuration behind that connection with the carriers and delivery options you want to offer.

Configuration

Register the provider on the Fulfillment Module, and register the plugin so its build output is loaded:

Define the Fulfillment Module once. If it appears twice in modules, the last definition wins and the provider in the earlier one is never registered — which makes every cart that references an nShift shipping option fail.

If your client secret contains $, do not escape it as \$ in .env — dotenv keeps the backslash and nShift answers invalid_client. Wrap the value in quotes instead.

Provider options

Check weight_unit. Medusa does not define a unit for variant.weight. The default "kg" matches earlier versions of this plugin; if your catalogue stores grams, set weight_unit: "g" or nShift will price a 500 g shirt as 500 kg.

Check prices_tax_inclusive. nShift Checkout prices are normally the consumer-facing gross price, hence the true default. Set it to false if your configuration holds net prices, otherwise your cart's tax totals will be wrong.

Creating shipping options in the admin

1. Settings → Locations & Shipping → your location → Shipping options → Create.
2. Set Price type to Calculated so the price comes from nShift.
3. Pick nShift as the provider and choose one of the delivery options it lists. Each Medusa shipping option maps to exactly one nShift delivery option.

The chosen delivery option is stored on shipping_option.data.option_id. If that dropdown is empty or errors, the message tells you why — most often a missing default_country / default_postal_code, or no delivery options configured for that country.

Storefront usage

Calculated options come back from GET /store/shipping-options without a price; fetch each price with POST /store/shipping-options/:id/calculate, then add the method to the cart.

data accepted when adding a shipping method

Both snake_case and the nShift widget's camelCase spelling are accepted.

Selections are validated against the delivery option before the method is stored: an unknown pickup point, time slot or addon is rejected with a 400 naming it. Addon prices are added to the shipping price.

Anything else you put in data is preserved verbatim, so you can carry your own state through checkout.

What ends up on the shipping method

After fulfillment, fulfillment.data additionally carries nshift_shipment_id, nshift_order_id, nshift_carrier and nshift_carrier_product.

Behaviour and error handling

The provider never breaks a cart. calculatePrice reports an option as unavailable — no calculated_amount — instead of throwing, whenever:

• the cart has no country or postal code yet,
• nShift does not return the option for that address (wrong country route, weight over the limit, a price rule excluding it),
• nShift returns the option without a price,
• the nShift API is unreachable, times out or errors,
• the shipping option has no nShift delivery option attached.

Medusa treats a missing price as "not available in this context": refreshCartShippingMethodsWorkflow removes the shipping method, and an explicit selection is rejected with 400 … do not have a price. So changing the shipping country to one a carrier does not serve drops that method rather than failing the address update. Every case is logged with the nShift status and issues[] so you can see the reason in the server log.

Errors are raised where they are actionable instead:

Not covered yet

• Split shipments (nShift's /split-shipments/* endpoints).
• Return shipments — createReturnFulfillment is not implemented.
• Labels and tracking numbers: booking and printing still happen in your Book & Print platform, so createFulfillment returns no labels.
• Own Pickup Locations API management.
• Badges, certifications and Klarna delivery types are read from nShift but not surfaced on the shipping method.

License

MIT