banner iconIntroducing Bloom: Build Medusa stores with AI
Overview
Icon for Mondial Relay

Mondial Relay

Ship orders with Mondial Relay

medusa-mondialrelay

A Medusa v2 fulfillment provider plugin for Mondial Relay shipping services. Supports both Point Relais (pickup point) and Home Delivery options with real-time pricing via @frontboi/mondial-relay.

Features

  • 🏪 Point Relais - Pickup point delivery with interactive selector
  • 🏠 Home Delivery - Door-to-door delivery (+3€ surcharge)
  • 💰 Real Pricing - Uses official Mondial Relay pricing via Copy to clipboard@frontboi/mondial-relay
  • 🌍 Multi-country - FR, BE, LU, NL, ES, PT, DE, IT, AT
  • 🏷️ Label Generation - PDF shipping label creation
  • 📦 Shipment Tracking - Tracking number generation
  • 🖨️ Admin Widget - Print labels directly from order details

Requirements

  • Medusa v2.0+
  • Node.js 18+
  • Mondial Relay API credentials (contact Mondial Relay for API access)

Installation

npm install medusa-mondialrelay

Configuration

1. Add the plugin to medusa-config.ts

// medusa-config.ts
import { defineConfig, loadEnv } from "@medusajs/framework/utils"


loadEnv(process.env.NODE_ENV || "development", process.cwd())


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",
    },
  },


  // Register the plugin
  plugins: [
    {
Important: You need to register the plugin in both Copy to clipboardplugins (for admin extensions) and Copy to clipboardmodules (for the fulfillment provider).

2. Environment Variables

Create or update your Copy to clipboard.env file:

# Mondial Relay API Credentials
MONDIAL_RELAY_LOGIN=your_login
MONDIAL_RELAY_PASSWORD=your_password
MONDIAL_RELAY_CUSTOMER_ID=your_customer_id
MONDIAL_RELAY_CULTURE=fr-FR
MONDIAL_RELAY_API_URL=https://api.mondialrelay.com/Web_Services.asmx


# Business Address (sender)
BUSINESS_FIRSTNAME=John
BUSINESS_LASTNAME=Doe
BUSINESS_STREET=123 Main Street
BUSINESS_POSTCODE=75001
BUSINESS_CITY=Paris
BUSINESS_COUNTRY=FR
BUSINESS_EMAIL=contact@yourstore.com
BUSINESS_PHONE=0612345678

3. Create Shipping Options

In the Medusa Admin, create shipping options:

Point Relais Option

  1. Go to Settings → Locations & Shipping
  2. Select your location and add a shipping option
  3. Set:
    • Name: Copy to clipboardMondial Relay - Point Relais
    • Price Type: Copy to clipboardCalculated
    • Fulfillment Provider: Copy to clipboardmondialrelay-point-relais

Home Delivery Option

  1. Create another shipping option
  2. Set:
    • Name: Copy to clipboardMondial Relay - Livraison à Domicile
    • Price Type: Copy to clipboardCalculated
    • Fulfillment Provider: Copy to clipboardmondialrelay-home-delivery
Note: The plugin automatically applies +3€ surcharge for home delivery options.

Free Shipping

Configuration

You can configure a cart total threshold above which shipping becomes free:

// In medusa-config.ts, provider options:
options: {
  // ... other options
  freeShippingThreshold: 50, // Free shipping when cart >= 50€
  freeShippingAppliesTo: "all", // "all" | "pickup" | "home"
}

Options

Option Type Default Description Copy to clipboardfreeShippingThreshold Copy to clipboardnumber Copy to clipboardundefined Cart total (in euros) above which shipping is free Copy to clipboardfreeShippingAppliesTo Copy to clipboard"all" | "pickup" | "home" Copy to clipboard"all" Which delivery types get free shipping

Free Shipping Modes

  • Copy to clipboard"all" (default): Free shipping applies to both Point Relais and Home Delivery
  • Copy to clipboard"pickup": Free shipping only for Point Relais (Home Delivery still charged)
  • Copy to clipboard"home": Free shipping only for Home Delivery (Point Relais still charged)

Examples

// Free shipping for ALL delivery types when cart >= 50€
options: {
  freeShippingThreshold: 50,
  freeShippingAppliesTo: "all", // or omit (default)
}


// Free shipping ONLY for Point Relais when cart >= 50€
// Home delivery still has normal pricing
options: {
  freeShippingThreshold: 50,
  freeShippingAppliesTo: "pickup",
}


// Free shipping ONLY for Home Delivery when cart >= 100€
// Point Relais still has normal pricing
options: {
  freeShippingThreshold: 100,
  freeShippingAppliesTo: "home",
}

Storefront Integration

Pass the cart total when setting the shipping method:

await setShippingMethod({
  cartId: cart.id,
  shippingMethodId: selectedOptionId,
  data: {
    shipping_option_name: "Mondial Relay - Point Relais",
    cart_total: cart.total / 100, // Convert from cents to euros
    // ... other data
  }
})

When Copy to clipboardcart_total >= freeShippingThreshold and the delivery type matches Copy to clipboardfreeShippingAppliesTo, the shipping cost will be 0€.

Pricing

Real-time Pricing via @frontboi/mondial-relay

The plugin uses Copy to clipboard@frontboi/mondial-relay for official Mondial Relay pricing based on:

  • Package weight (250g to 30kg)
  • Destination country (FR, BE, LU, NL, ES, PT, DE, IT, AT)

Home Delivery Surcharge

Home delivery options automatically add a +3€ surcharge to the base Point Relais price.

Example Prices (France)

Weight Point Relais Home Delivery 500g ~3.99€ ~6.99€ 1kg ~4.49€ ~7.49€ 2kg ~5.49€ ~8.49€ 5kg ~7.99€ ~10.99€

Prices are fetched in real-time from Mondial Relay's official pricing grid.

Storefront Integration

Point Relais Selector

For Point Relais delivery, integrate a pickup point selector. The plugin expects:

await setShippingMethod({
  cartId: cart.id,
  shippingMethodId: selectedOptionId,
  data: {
    shipping_option_name: "Mondial Relay - Point Relais",
    parcel_shop_id: "020340",
    parcel_shop_name: "Relay Shop Name",
    parcel_shop_address: "123 Shop Street",
    parcel_shop_city: "Paris",
    parcel_shop_postcode: "75001",
  }
})

Recommended: @frontboi/mondial-relay

npm install @frontboi/mondial-relay
import { ParcelShopSelector } from "@frontboi/mondial-relay"


<ParcelShopSelector
  postalCode="75001"
  countryCode="FR"
  brandIdAPI={process.env.NEXT_PUBLIC_MONDIAL_RELAY_BRAND_ID}
  onParcelShopSelected={(shop) => {
    // Handle selection
  }}
/>

Home Delivery

await setShippingMethod({
  cartId: cart.id,
  shippingMethodId: selectedOptionId,
  data: {
    shipping_option_name: "Mondial Relay - Livraison à Domicile",
  }
})

Admin Features

Label Printing Widget

The plugin adds a widget to the order details page for:

  • ✅ Tracking number display
  • ✅ Pickup point info (if applicable)
  • 🖨️ "Print Label" button for PDF download

Supported Countries

Code Country FR France BE Belgium LU Luxembourg NL Netherlands ES Spain PT Portugal DE Germany IT Italy AT Austria

License

MIT © Théo Daguier

Links

You may also like

Browse all integrations

Build your own

Develop your own custom integraiton

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

payment iconcart icongift icon
Get started
gift card interface

Ready to build your custom commerce setup?

Starter DocsGet started