S

Sendcloud plugin

Name: Sendcloud plugin
Author: Saphes

SendCloud integration plugin for Medusa v2.21.2

Featured on Medusa

npm install @saphes/medusa-sendcloud-plugin

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:

yarn add @medita/medusa-sendcloud-plugin

Local Development

Install dependencies in the plugin folder:

1cd sendcloud-medusa
2yarn install

Build the plugin:

yarn build

For development with hot-reloading:

yarn dev

Configuration

Using as a Module Provider (Recommended)

In your :

1import { loadEnv, defineConfig, Modules } from "@medusajs/framework/utils"
2
3module.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: [
        {
          resolve: "@medita/medusa-sendcloud-plugin/providers/sendcloud-fulfillment",
          id: "sendcloud-fulfillment",
          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',
          },
        },
      ],
    },
  },
]
35});

Alternative: Using as a Plugin

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

1plugins: [
{
  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',
  },
},
12],

Environment Variables

Add these to your file:

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

Configuration Options

Type	Required	Default	Description
string	✅	-	Your SendCloud API public key
string	✅	-	Your SendCloud API secret key
string	❌		SendCloud API base URL
string	❌	-	Your SendCloud partner ID (if applicable)
string	❌		Default country code for shipments (ISO 2-letter format)

Note on : 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: (Netherlands), (Germany), (France), (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 IDs.

The plugin adds two mutually exclusive intra-EU settings in the Sendcloud shipping-options admin page:

Do not specify product origin for intra-EU shipments: keeps , but omits their field. Use this when products can have a non-ISO origin such as .
Omit parcel items for intra-EU shipments: omits the entire payload. This overrides and disables the origin setting; products will not be shown in Sendcloud's Items list.

Leave both settings disabled for international shipments: 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

- List all shipments
- Get shipment details
- Create a shipment
- Update a shipment
- Delete a shipment

Webhook Routes

- Handle SendCloud webhooks for tracking updates

Workflows

The plugin includes the following workflows:

- Creates a SendCloud shipment for an order
- Updates tracking information from webhooks

Module Services

SendCloudModuleService

Main service for managing SendCloud shipments:

1const sendCloudService = container.resolve("sendcloud");
2
3// Create a shipment
4const shipment = await sendCloudService.createShipment({
5  order_id: "order_123",
6  // ... shipment data
7});
8
9// Get shipments for an order
10const shipments = await sendCloudService.getShipmentByOrderId("order_123");