SendCloud

SendCloud Plugin for Medusa v2.9

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

Compatibility

• Medusa v2.9.0+: 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.9.0 compatibility with latest framework patterns
• Enhanced type safety with Zod validation
• Streamlined plugin architecture without loaders

Installation

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: {
    [Modules.FULFILLMENT]: {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "@medita/medusa-sendcloud-plugin/providers/sendcloud-fulfillment",

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.

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