Sendcloud

Sendcloud Plugin for Medusa v2

A comprehensive SendCloud integration plugin for MedusaJS v2.21.2 that provides shipping and fulfillment capabilities.

Compatibility

• Medusa v2.21.2+: Fully compatible
• Medusa v2.8.x and below: Not supported
• Node.js: v20+ required
• TypeScript: v5.6+ recommended

Features

• SendCloud shipment creation and management
• Order fulfillment integration
• Webhook handling for tracking updates
• Admin UI for shipment management
• Automated shipping workflows
• Full Medusa v2.21.2 compatibility with latest framework patterns
• Enhanced type safety with Zod validation
• Streamlined plugin architecture without loaders

Installation

Install from npm:

1
yarn add @medita/medusa-sendcloud-plugin

Local Development

1. Install dependencies in the plugin folder:

12
cd sendcloud-medusa
yarn install

1. Build the plugin:

1
yarn build

1. For development with hot-reloading:

1
yarn dev

Configuration

Using as a Module Provider (Recommended)

In your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
import { loadEnv, defineConfig, Modules } from "@medusajs/framework/utils"

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS,
      adminCors: process.env.ADMIN_CORS,
      authCors: process.env.AUTH_CORS,
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    },
  },
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      dependencies: [Modules.PRODUCT],
      options: {
        providers: [
          {

Alternative: Using as a Plugin

You can also register it as a plugin (includes additional features like webhooks and admin APIs):

123456789101112
plugins: [
  {
    resolve: "@medita/medusa-sendcloud-plugin",
    options: {
      apiKey: process.env.SENDCLOUD_API_KEY,
      apiSecret: process.env.SENDCLOUD_API_SECRET,
      baseUrl: process.env.SENDCLOUD_BASE_URL,
      partnerId: process.env.SENDCLOUD_PARTNER_ID,
      defaultCountry: process.env.SENDCLOUD_DEFAULT_COUNTRY || 'NL',
    },
  },
],

Environment Variables

Add these to your Copy to clipboard.env file:

12345
SENDCLOUD_API_KEY=your_api_key
SENDCLOUD_API_SECRET=your_api_secret
SENDCLOUD_BASE_URL=https://panel.sendcloud.sc/api/v2
SENDCLOUD_PARTNER_ID=your_partner_id
SENDCLOUD_DEFAULT_COUNTRY=NL  # Optional: Default country code (ISO 2-letter format)

Configuration Options

Option Type Required Default Description Copy to clipboardapiKey string ✅ - Your SendCloud API public key Copy to clipboardapiSecret string ✅ - Your SendCloud API secret key Copy to clipboardbaseUrl string ❌ Copy to clipboardhttps://panel.sendcloud.sc/api/v2 SendCloud API base URL Copy to clipboardpartnerId string ❌ - Your SendCloud partner ID (if applicable) Copy to clipboarddefaultCountry string ❌ Copy to clipboardNL Default country code for shipments (ISO 2-letter format)

Note on Copy to clipboarddefaultCountry: This is used as a fallback when:

• Product origin country is not specified (affects customs declarations)
• Sender address country is missing
• Return shipment origin country is not available

Common values: Copy to clipboardNL (Netherlands), Copy to clipboardDE (Germany), Copy to clipboardFR (France), Copy to clipboardBE (Belgium), etc.

Shipping options and product origin

Shipping methods are loaded from the configured Sendcloud V2 API endpoint. Use the method IDs returned by that endpoint when creating Medusa shipping options; V3 shipping option codes are not valid V2 parcel Copy to clipboardshipping_method IDs.

The plugin adds a "Do not send product origin (intra-EU only)" checkbox in the Sendcloud shipping-options admin page.

• Enable it for an intra-EU shipping option when products can have a non-ISO origin such as Copy to clipboardEU.
• When enabled, Copy to clipboardparcel_items are still sent, but their Copy to clipboardorigin_country field is omitted. Sendcloud therefore keeps the item details without receiving a non-ISO country value.
• Leave it disabled for international shipments: Copy to clipboardparcel_items and each product's valid ISO 3166-1 alpha-2 origin country are then sent as customs data.

Changing this setting can also synchronize the setting to existing order shipping-method snapshots from the Sendcloud shipping-options page. Changing the actual Sendcloud method still requires creating or updating the corresponding Medusa shipping option.

API Routes

The plugin provides the following API routes:

Admin Routes

• Copy to clipboardGET /admin/sendcloud - List all shipments
• Copy to clipboardGET /admin/sendcloud/:id - Get shipment details
• Copy to clipboardPOST /admin/sendcloud - Create a shipment
• Copy to clipboardPUT /admin/sendcloud/:id - Update a shipment
• Copy to clipboardDELETE /admin/sendcloud/:id - Delete a shipment

Webhook Routes

• Copy to clipboardPOST /webhooks/sendcloud - Handle SendCloud webhooks for tracking updates

Workflows

The plugin includes the following workflows:

• Copy to clipboardcreateShipmentWorkflow - Creates a SendCloud shipment for an order
• Copy to clipboardupdateTrackingWorkflow - Updates tracking information from webhooks

Module Services

SendCloudModuleService

Main service for managing SendCloud shipments:

12345678910
const sendCloudService = container.resolve("sendcloud");

// Create a shipment
const shipment = await sendCloudService.createShipment({
  order_id: "order_123",
  // ... shipment data
});

// Get shipments for an order
const shipments = await sendCloudService.getShipmentByOrderId("order_123");

License

MIT

npx medusa plugin:build yalc update @medita/medusa-sendcloud-plugin npx medusa plugin:add @medita/medusa-sendcloud-plugin