Sendcloud plugin
SendCloud integration plugin for Medusa v2.21.2
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:
Local Development
- Install dependencies in the plugin folder:
- Build the plugin:
yarn build- For development with hot-reloading:
yarn devConfiguration
Using as a Module Provider (Recommended)
In your :
Alternative: Using as a Plugin
You can also register it as a plugin (includes additional features like webhooks and admin APIs):
Environment Variables
Add these to your file:
Configuration Options
| Option | 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:
License
MIT
npx medusa plugin:build yalc update @medita/medusa-sendcloud-plugin npx medusa plugin:add @medita/medusa-sendcloud-plugin