Colissimo

medusa-colissimo

Colissimo fulfillment provider for MedusaJS v2.

Supported Delivery Options

Installation

pnpm add medusa-colissimo

Configuration

Environment Variables

1COLISSIMO_CONTRACT_NUMBER=your_contract_number
2COLISSIMO_PASSWORD=your_password
3
4BUSINESS_NAME="Your Company"
5BUSINESS_STREET="123 Rue Example"
6BUSINESS_CITY="Paris"
7BUSINESS_POSTCODE="75001"

Get your credentials from Colissimo Box.

Medusa Config

1// medusa-config.ts
2module.exports = defineConfig({
3  // Register plugin for API routes and admin extensions
4  plugins: [
5    {
6      resolve: "medusa-colissimo",
7      options: {},
8    },
9  ],
10  // Register fulfillment provider
11  modules: [
12    {
13      resolve: "@medusajs/medusa/fulfillment",
14      options: {
15        providers: [
16          {
17            resolve: "medusa-colissimo/providers/colissimo",
18            id: "colissimo",
19            options: {
20              contractNumber: process.env.COLISSIMO_CONTRACT_NUMBER,
21              password: process.env.COLISSIMO_PASSWORD,
22              businessAddress: {
23                companyName: process.env.BUSINESS_NAME,
24                line2: process.env.BUSINESS_STREET,
25                city: process.env.BUSINESS_CITY,
26                zipCode: process.env.BUSINESS_POSTCODE,
27                countryCode: "FR",
28              },
29              // Optional
30              enableReturns: true,
31              enableCalculatedPricing: true,
32              pricingTable: {
33                DOM: {
34                  FR: [
35                    { maxWeight: 0.25, price: 495 },
36                    { maxWeight: 0.5, price: 615 },
37                    { maxWeight: 1, price: 715 },
38                    { maxWeight: 2, price: 815 },
39                    { maxWeight: 5, price: 1095 },
40                    { maxWeight: 10, price: 1595 },
41                    { maxWeight: 30, price: 2295 },
42                  ],
43                },
44                // Add DOS, A2P pricing as needed
45              },
46            },
47          },
48        ],
49      },
50    },
51  ],
52});

Admin Widgets

Two widgets are included for the order details page:

Fulfillment Form (sidebar) - Select items, set weight manually if needed, create fulfillment.

Fulfillment Display (after details) - Shows tracking number, delivery type, download/print label buttons.

Manual Weight

Products should have weights defined on their variants (in grams). If not, or if you need to override after weighing the package, check "Saisir le poids manuellement" and enter the weight in grams.

API Endpoints

Widget Token

GET /store/colissimo/widget-token

Returns a token for the Colissimo frontend widget (valid 30 minutes).

Search Relay Points

POST /store/colissimo/relay-points

{
  "zipCode": "75001",
  "city": "Paris",
  "countryCode": "FR"
}

Get Relay Point

GET /store/colissimo/relay-points/:id?zipCode=75001

Frontend Integration

For relay point delivery, store the selected point ID in the shipping address metadata:

1await medusa.carts.update(cartId, {
2  shipping_address: {
3    // ... address fields
4    metadata: {
5      relay_point_id: selectedPoint.id,
6    },
7  },
8});

Colissimo Widget

You can use the official Colissimo widget for relay point selection:

1// Get token from your backend
2const { token } = await fetch('/store/colissimo/widget-token').then(r => r.json());
3
4// Initialize widget (requires jQuery and Mapbox GL)
5$('#widget-container').frameColissimoOpen({
6  URLColissimo: 'https://ws.colissimo.fr',
7  callBackFrame: 'onPointSelected',
8  ceCountry: 'FR',
9  ceZipCode: customerZipCode,
10  ceTown: customerCity,
11  token: token
12});
13
14function onPointSelected(point) {
15  // point.identifiant is the relay point ID
16  $('#widget-container').frameColissimoClose();
17}

Limitations

• Label cancellation is not supported by Colissimo API. Cancel manually in Colissimo Box.
• Max weight: 30kg
• Optimized for France. International shipping may need additional setup.

Development

1pnpm install
2pnpm build
3pnpm test

License

MIT