S4f spreadconnect

Spreadconnect for Medusa

s4f-spreadconnect is a Medusa plugin developed by SHOP4FANS. It connects Medusa to Spreadconnect. It imports products, calculates shipping, submits paid orders, and records fulfillment and tracking updates.

Unofficial integration: This plugin is not affiliated with, endorsed by, or an official product of Spreadconnect. Spreadconnect is a third-party service.

This release requires Medusa 2.22.1 and Node.js 22.22.0 or later. Use the same Medusa version in the host application.

Install

Create a stock location and a shipping profile in Medusa Admin. Use their IDs in the configuration below.

Register the plugin and fulfillment provider in medusa-config.ts. Merge these entries with your existing configuration and providers.

Required environment variables:

The token is configured separately for the plugin module and fulfillment provider because Medusa modules are isolated. The fulfillment provider does not inject the product/webhook module.

The default fulfillment provider ID is spreadconnect_spreadconnect: Medusa composes it from the provider's static identifier (spreadconnect) and configured ID (spreadconnect). If the provider is registered with a different id, set the resulting full ID in the plugin option fulfillmentProviderId.

Medusa fulfillment setup

Configure the following through Medusa Admin or the corresponding Admin APIs:

1. Create or choose the Stock Location used for Spreadconnect.
2. Enable spreadconnect_spreadconnect on that Stock Location.
3. Create a Fulfillment Set for the location.
4. Add a Service Zone covering the supported destination countries.
5. Create or choose the Shipping Profile used by Spreadconnect products.
6. Ensure imported Spreadconnect products use that Shipping Profile. Set shippingProfileId to make product imports assign it.
7. In the Service Zone, create two Shipping Options with price type calculated, the Spreadconnect provider, and the same Shipping Profile.

The provider exposes exactly these fulfillment options:

Choose spreadconnect-standard for the Standard Shipping Option and spreadconnect-express for Express. The provider rejects mismatched IDs and preferred_type values.

Activate the integration

1. Set the environment variables shown above. Use your Spreadconnect API URL and token.
2. Set MEDUSA_BACKEND_URL to the public HTTPS backend URL.
3. Set a webhook secret. The plugin sends this secret when it registers subscriptions.
4. Apply the plugin migrations with npx medusa db:migrate.
5. Restart the backend and its worker processes.
6. Open Spreadconnect in Medusa Admin.
7. Select Register webhooks. Check each result. Retry if any registration fails.
8. Create or update an article in Spreadconnect to send its product webhook.
9. Assign the imported product to your sales channel and publish it in Medusa Admin.

Imports use defaultCurrencyCode, which defaults to eur. Configure the same currency and appropriate tax settings in Medusa. Product prices use Spreadconnect d2cPrice values without conversion.

Product creation and updates set the product to draft. An update therefore removes a published product from the storefront until you publish it again. The plugin does not select sales channels.

The plugin receives product changes through webhooks. It does not perform an initial bulk catalog import.

Connect a storefront

Use the normal Medusa Store API or Medusa JS SDK. The storefront does not need Spreadconnect credentials or custom checkout endpoints.

Before you request shipping prices, save the customer email and shipping address on the cart. Include a phone number in the shipping address. Spreadconnect requires these fields. The cart region determines the currency.

Backend workflow hooks read the saved cart email and currency. Do not pass them in shipping-method data. Client values cannot override the saved cart values.

A storefront that omits phone numbers must collect and save a phone number before shipping calculation. Standard Medusa fields support this requirement. Product visibility still requires a published product, a sales channel, a linked stock location, and a matching publishable API key.

Each shipping calculation creates a temporary Spreadconnect order in state NEW, then cancels it. Standard and Express use separate calculations. Shipping prices use major currency units and include tax. Cancellation failures cause the calculation to fail after three attempts.

Stock updates and checkout checks

The job in src/jobs/spreadconnect-stock-sync.ts runs daily at 0 3 * * *. The scheduler determines the time zone. Set your worker time zone explicitly if 03:00 must match a local time.

The job reads paginated stock from Spreadconnect and updates imported variants at defaultStockLocationId. It changes inventory quantities only. It does not unpublish products or change sales channels.

Zero stock sets the inventory quantity to zero. Missing or invalid stock leaves the previous quantity unchanged. The job skips unsupported inventory links, including bundles, and logs the skipped count. If a later page fails, earlier batches remain saved. The next daily run checks them again.

Live stock checks also run when a customer:

• Creates a cart with items.
• Adds items to a cart.
• Changes a line-item quantity.
• Creates a payment session.
• Completes checkout.

The plugin reads stored variant data and combines quantities for each SKU. A cart cannot bypass the check through client metadata. Non-Spreadconnect products use normal Medusa inventory checks.

Insufficient stock returns spreadconnect_insufficient_stock. An API failure or invalid stock response returns spreadconnect_stock_check_failed. Both use Medusa's standard HTTP 400 error response. The storefront can display these errors through its normal cart and checkout error handling.

These checks do not reserve stock at Spreadconnect. Supplier stock can change after a check. Completed-cart retries remain idempotent and do not trigger a new stock check.

Orders and webhooks

The plugin handles these events:

order.placed and payment.captured trigger payment reconciliation. Production starts only after the payment collection is complete and fully captured. Authorization or partial capture does not start production.

Submission sends a CONFIRMED Spreadconnect order with a stable medusa:<order_id> reference. The plugin saves the remote order ID on the shipping method. Order.processed creates the Medusa fulfillment later. Manual fulfillment requires an existing submission and does not create another production order.

Webhook delivery uses POST /spreadconnect/webhooks. The endpoint verifies the X-SPRD-SIGNATURE HMAC and saves a database receipt before it returns 202. It does not call Spreadconnect during acknowledgment.

A scheduled job processes up to 50 due receipts each minute. Failed processing uses increasing retry delays, up to one hour. Identical deliveries share one receipt. Order locks prevent duplicate fulfillment and shipment changes. Product imports share a lock to protect global options.

Keep a Medusa worker with scheduled jobs enabled. For multiple backend or worker processes, configure Medusa's shared locking provider, such as Redis. A process-local lock cannot coordinate separate processes.

Recovery and limits

Stock lookup failures keep the receipt pending. They do not disable inventory management or enable backorders. A retry completes partial product imports. An older pending article receipt is ignored when a newer receipt for that article has completed. This uses receipt time, not an upstream event sequence.

An uncertain production response records submission_unknown. The plugin does not submit again automatically, because the first request may have succeeded. Check the remote order using its external reference. A later processed webhook can attach the remote order and continue fulfillment. Resolve a request that never reached Spreadconnect before you clear its submission marker.

Shipment processing waits until the relevant remote items have shipped. It retries when a fulfillment or tracking data is not yet available. It does not mark quantities shipped at production submission.

A remote cancellation uses Medusa's order cancellation workflow. This can refund captured payments and cancels the whole Medusa order. Use separate orders for products whose cancellation must remain independent.

Returns are not supported. Cancel an existing fulfillment through Medusa's normal cancellation flow. If Spreadconnect refuses cancellation, the provider returns an error.

Receipts retain webhook payloads, which can contain customer information. Set a retention policy for completed receipts in your deployment. Pending receipts must remain available for retries.

Development

Tests use anonymized Spreadconnect responses in tests/fixtures/spreadconnect. SDK replay tests pass captured response bodies through the installed SDK without remote API calls.

npm run test:install installs the built tarball and its dependencies in a temporary project. It checks Medusa plugin discovery and loads the packaged backend entry points. This command requires access to the npm registry.

Run database tests against an isolated local database whose name contains test:

The optional npm run test:staging requires SPREADCONNECT_RUN_STAGING_CONTRACT=true, SPREADCONNECT_STAGING_BASE_URL, SPREADCONNECT_STAGING_TOKEN, and SPREADCONNECT_STAGING_ORDER_FIXTURE. The fixture must be a valid SDK CreateOrder JSON payload. This test creates and cancels quotes and creates a confirmed staging order. Use a staging account only.

Links and support

• Spreadconnect API documentation
• Spreadconnect website
• SHOP4FANS
• Plugin issues
• Plugin author: Konrad

License

This plugin uses the MIT License. Its dependencies retain their own licenses.