Makesend

Makesend Fulfillment Plugin for MedusaJS

A MedusaJS plugin that integrates Makesend logistics services for Thai e-commerce fulfillment. Built specifically for Medusa v2.11.3+.

Features

• ✅ Fulfillment Provider - Native integration using Medusa v2 fulfillment architecture
• ✅ Shipping Rate Calculation - Real-time pricing via Makesend Copy to clipboard/order/calculateFee API
• ✅ Order Creation - Automatically create Makesend shipments when fulfilling orders
• ✅ Order Cancellation - Cancel shipments through the Makesend API
• ✅ Webhook Support - Receive status updates and parcel size adjustments with automatic fulfillment tracking
• ✅ Admin Tracking Widget - View tracking information directly in order details page
• ✅ Temperature Control - Support for Normal, Chill, and Frozen deliveries
• ✅ Postal Code Lookup - Automatic Thai address validation and district mapping
• ✅ Custom Workflows - Integrated Medusa workflows for shipment creation and fulfillment
• ✅ Testing Scripts - Built-in webhook testing tools for local development

Installation

12345
# Using yarn
yarn add medusa-plugin-makesend

# Using npm
npm install medusa-plugin-makesend

Configuration

1. Add Environment Variables

Create or update your Copy to clipboard.env file:

1
MAKESEND_API_KEY=your_makesend_api_key

2. Configure Medusa

Add the plugin to your Copy to clipboardmedusa-config.ts:

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

module.exports = defineConfig({
  // Register the fulfillment provider
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          // Keep default manual provider
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
          // Add Makesend provider
          {
            resolve: "medusa-plugin-makesend/providers/makesend",
            id: "makesend",
            options: {
              apiKey: process.env.MAKESEND_API_KEY,

3. Create Shipping Options

After installation, create shipping options in Medusa Admin:

1. Navigate to Settings → Fulfillment
2. Select Makesend provider
3. Create shipping options using the fulfillment option IDs below

Provider Options

The Makesend provider supports the following configuration options:

Option Type Required Default Description Copy to clipboardapiKey string Yes - Your Makesend API key for authentication Copy to clipboardbaseUrl string No Copy to clipboardhttps://apis.makesend.asia/oapi/api Base URL for Makesend API endpoints Copy to clipboardtrackingBaseUrl string No Copy to clipboardhttps://app.makesend.asia Base URL for tracking links Copy to clipboardlabelBaseUrl string No Copy to clipboardhttps://app.makesend.asia Base URL for shipping label links Copy to clipboardstatusWebhookUrl string No - URL for Makesend to send status update webhooks Copy to clipboardparcelSizeWebhookUrl string No - URL for Makesend to send parcel size update webhooks Copy to clipboarddebug boolean No Copy to clipboardfalse Enable debug logging for API requests

Example with all options:

123456789
{
  apiKey: process.env.MAKESEND_API_KEY,
  baseUrl: "https://apis.makesend.asia/oapi/api",
  trackingBaseUrl: "https://app.makesend.asia",
  labelBaseUrl: "https://app.makesend.asia",
  statusWebhookUrl: "https://your-domain.com/store/makesend/webhook/status",
  parcelSizeWebhookUrl: "https://your-domain.com/store/makesend/webhook/parcel-size",
  debug: true,
}

Fulfillment Options

The plugin provides three shipping options:

Option ID Name Temperature Copy to clipboardmakesend-standard Makesend Standard Delivery Normal (0) Copy to clipboardmakesend-chill Makesend Chill Delivery Chill (1) Copy to clipboardmakesend-frozen Makesend Frozen Delivery Frozen (2)

Supported Parcel Sizes

ID Code Size 6 s80 S+ (S80) 7 s100 M (S100)

Webhooks

Configure webhook URLs in your Makesend dashboard to receive automatic updates:

Status Updates

Endpoint: Copy to clipboardhttps://your-domain.com/store/makesend/webhook/status

Automatically updates fulfillment tracking when shipment status changes. Supported status codes:

• Copy to clipboardPENDING - Order pending pickup
• Copy to clipboardSHIPPED - Package shipped
• Copy to clipboardARRIVED_HUB - Arrived at hub
• Copy to clipboardSORTED - Package sorted
• Copy to clipboardDELIVERING - Out for delivery
• Copy to clipboardDELIVERED - Successfully delivered (marks fulfillment as delivered)
• Copy to clipboardDELIVERY_FAILED - Delivery attempt failed
• Copy to clipboardRETURNED - Returned to sender
• Copy to clipboardCANCELED - Shipment canceled

Parcel Size Updates

Endpoint: Copy to clipboardhttps://your-domain.com/store/makesend/webhook/parcel-size

Receives notifications when actual parcel size differs from declared size.

Testing Webhooks Locally

The plugin includes scripts for testing webhooks during development:

1234567891011121314
# Make script executable (Unix/Linux/macOS)
chmod +x scripts/test-webhooks.sh

# Test all webhooks
./scripts/test-webhooks.sh all

# Test with specific tracking ID and status
./scripts/test-webhooks.sh all --tracking EXSS2601121002503 --status DELIVERED

# Test only status webhook
./scripts/test-webhooks.sh status --tracking YOUR_TRACKING_ID

# Test only parcel size webhook
./scripts/test-webhooks.sh parcel-size --tracking YOUR_TRACKING_ID

See scripts/README.md for detailed testing documentation.

API Routes

Store Routes

Endpoint Method Description Copy to clipboard/store/plugin GET Plugin health check Copy to clipboard/store/makesend/webhook/status POST Receive status update webhooks from Makesend Copy to clipboard/store/makesend/webhook/parcel-size POST Receive parcel size update webhooks from Makesend

Admin Routes

Endpoint Method Description Copy to clipboard/admin/plugin GET Admin plugin health check Copy to clipboard/admin/makesend/provinces GET Get list of Thai provinces Copy to clipboard/admin/makesend/districts GET Get districts filtered by province Copy to clipboard/admin/makesend/parcel-sizes GET Get supported parcel sizes Copy to clipboard/admin/makesend/settings/makesend GET/POST Get or update Makesend settings

Admin UI

The plugin provides several admin extensions:

Makesend Tracking Widget

Displays on the order details page with:

• Tracking ID with external link to Makesend tracking
• Receiver information
• Pickup and delivery locations
• Status history timeline with timestamps
• Delivery proof information (when available)

Settings Page

Navigate to Settings → Makesend to configure:

• API credentials
• Sender information (name, phone, address)
• Default pickup location
• Default parcel sizes
• Temperature control preferences

Reference Data

The plugin includes comprehensive Thai logistics data in the Copy to clipboard/data directory:

• Copy to clipboardprovince.json - Thai provinces (77 provinces)
• Copy to clipboarddistrict.json - Districts with province associations
• Copy to clipboardsubDistrict.json - Sub-districts with district associations
• Copy to clipboardthailand_addresses.json - Complete address database with postal codes
• Copy to clipboardparcelSizeList.json - Supported parcel sizes (S80, S100)
• Copy to clipboardparcelTypeList.json - Parcel type categories
• Copy to clipboardpickupTimeSlotList.json - Available pickup time slots
• Copy to clipboardpriceList.json - Pricing reference data
• Copy to clipboardshipmentStatusList.json - Complete list of shipment status codes
• Copy to clipboardbankCodeList.json - Bank codes for COD transactions

Custom Workflows

The plugin provides Medusa workflows for managing shipments:

Copy to clipboardcreateMakesendShipmentWorkflow

Creates a shipment in Makesend when fulfilling an order. Automatically:

• Fetches shipping option and stock location details
• Creates Makesend order via API
• Returns shipment data for fulfillment

Copy to clipboardcreateMakesendFulfillmentWorkflow

Complete fulfillment workflow that:

• Validates order and fulfillment data
• Creates Makesend shipment
• Updates fulfillment with tracking information

See src/workflows/README.md for workflow documentation.

Currency Note

Makesend API uses Satang (1 Baht = 100 Satang) for all monetary values. The plugin handles this automatically when calculating prices.

Development

1234567891011
# Install dependencies
yarn install

# Build the plugin
yarn build

# Run in development mode (with linked Medusa app)
yarn dev

# Test webhooks locally
./scripts/test-webhooks.sh

Documentation

• Makesend API Documentation - Complete API reference
• Supported Parcel Sizes - Parcel size specifications
• Webhook Testing Guide - Testing webhooks locally

Requirements

• Node.js >= 20
• MedusaJS v2.11.3 or higher
• Makesend API account and API key
• TypeScript 5.x (for development)

Repository

• GitHub: CivicAgroTech/medusa-plugin-makesend
• NPM: medusa-plugin-makesend

Author

CivicAgrotech Co., Ltd.
Website: https://civicagrotech.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (Copy to clipboardgit checkout -b feature/amazing-feature)
3. Commit your changes (Copy to clipboardgit commit -m 'Add some amazing feature')
4. Push to the branch (Copy to clipboardgit push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT