InPost Plugin for Medusa v2

Handle order fulfillments using InPost parcel lockers in Medusa v2.

SpearDevs Website

Features

• ✅ InPost parcel locker integration
• ✅ Shipment creation and management
• ✅ Point/locker selection API
• ✅ Order fulfillment processing
• ✅ Admin API for shipment management
• ✅ Store API for frontend integration
• ✅ Phone number validation
• ✅ Target point validation

Planned Features

• 🔄 Shipment document generation
• 🔄 Return shipments
• 🔄 Admin UI components
• 🔄 Shipment tracking
• 🔄 Webhook integration

Prerequisites

• Medusa v2 backend
• InPost account
• Node.js >= 18
• PostgreSQL

Installation

1. Install the plugin:

npm install medusa-plugin-inpost

2. Add environment variables to your .env file:

INPOST_BASE_URL=https://sandbox-api-shipx-pl.easypack24.net
INPOST_ORGANIZATION_ID=your_organization_id
INPOST_TOKEN=your_api_token
INPOST_DEFAULT_TEMPLATE=small

3. Register the provider in your medusa-config.js:

module.exports = defineConfig({
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          // default manual provider
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
          // InPost provider
          {
            resolve: "medusa-plugin-inpost/providers/inpost",
            id: "inpost",
            options: {
              base_url: process.env.INPOST_BASE_URL,
              token: process.env.INPOST_TOKEN,
              organization_id: process.env.INPOST_ORGANIZATION_ID,
              default_template: process.env.INPOST_DEFAULT_TEMPLATE || "medium",
            },
          },
        ],
      },
    },
  ],
  // plugins array is not needed for fulfillment providers
});

Configuration

Environment Variables

| Variable | Description | Required | Default | | ------------------------- | --------------------------- | -------- | -------- | | INPOST_BASE_URL | InPost API base URL | Yes | - | | INPOST_ORGANIZATION_ID | Your InPost organization ID | Yes | - | | INPOST_TOKEN | InPost API token | Yes | - | | INPOST_DEFAULT_TEMPLATE | Default package template | No | medium |

Package Templates

Available package templates:

• small - Small package
• medium - Medium package (default)
• large - Large package

API Endpoints

Admin API

Points Management

• GET /admin/inpost/points - Get all InPost points
• GET /admin/inpost/points/{id} - Get specific point

Shipments Management

• GET /admin/inpost/shipments - Get all shipments
• POST /admin/inpost/shipments - Create new shipment
• GET /admin/inpost/shipments/{id} - Get specific shipment
• PUT /admin/inpost/shipments/{id} - Update shipment
• DELETE /admin/inpost/shipments/{id} - Cancel shipment

Store API

Points for Frontend

• GET /store/inpost/points - Get all InPost points for frontend
• GET /store/inpost/points/{id} - Get specific point for frontend

Frontend Integration

Selecting InPost Point

When creating an order, the frontend needs to:

1. Fetch available InPost points:

const response = await fetch("/store/inpost/points");
const { points } = await response.json();

2. Include the selected point in the fulfillment data:

const fulfillmentData = {
  provider_id: "inpost",
  data: {
    target_point: "selected_point_id",
  },
};

3. Ensure the shipping address includes a valid phone number:

const shippingAddress = {
  first_name: "John",
  last_name: "Doe",
  phone: "+48123456789", // Required for InPost
  address_1: "Street 123",
  city: "Warsaw",
  country_code: "PL",
  postal_code: "00-001",
};

Usage with Fulfillment

Creating Fulfillment

// In your order processing
const fulfillment = await fulfillmentService.createFulfillment({
  provider_id: "inpost",
  data: {
    target_point: "POZ08A", // InPost point ID
  },
  items: orderItems,
  order: order,
});

Canceling Fulfillment

await fulfillmentService.cancelFulfillment({
  provider_id: "inpost",
  data: {
    shipmentId: "inpost_shipment_id",
  },
});

Troubleshooting

Common Issues

1. "Cannot read properties of undefined (reading 'prototype')" Error

This error occurs when the plugin is not properly configured. Make sure you:

1. Only configure the provider in modules, not in plugins
2. Use the correct resolve path: medusa-plugin-inpost/providers/inpost
3. Install the plugin before starting the server: npm install medusa-plugin-inpost

2. "No exports main defined" Error

This happens when there's a mismatch in the plugin structure. Ensure you:

1. Update to the latest version of the plugin
2. Clear node_modules and reinstall: rm -rf node_modules && npm install
3. Restart your development server

3. Plugin Not Found

If Medusa can't find the plugin:

1. Check the plugin is installed: npm ls medusa-plugin-inpost
2. Use the full path: medusa-plugin-inpost/providers/inpost
3. Make sure the plugin is built: Check for .medusa/server folder in the plugin directory

Example Complete Configuration

const { defineConfig } = require("@medusajs/utils");

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    // ... other project config
  },
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
          {
            resolve: "medusa-plugin-inpost/providers/inpost",
            id: "inpost",
            options: {
              base_url: process.env.INPOST_BASE_URL,
              token: process.env.INPOST_TOKEN,
              organization_id: process.env.INPOST_ORGANIZATION_ID,
              default_template: process.env.INPOST_DEFAULT_TEMPLATE || "medium",
            },
          },
        ],
      },
    },
  ],
});

Development

Building the Plugin

npm run build

Running in Development

npm run dev

Testing the Provider

Before using your InPost Fulfillment Provider, in the Medusa Admin:

1. Add the provider to a location:

   • Go to Settings → Locations
   • Select or create a location
   • Add InPost as a fulfillment provider

2. Create a shipping option:

   • Go to Settings → Shipping Options
   • Create a new shipping option
   • Select the location with InPost provider
   • Choose "InPost Parcel Locker" from fulfillment options

3. Test the integration:

   • Place a test order choosing the InPost shipping option
   • Ensure the shipping address includes a valid phone number
   • Include target_point in the fulfillment data
   • Create a fulfillment in the Medusa Admin

The fulfillment will be processed using your InPost provider!

Validation

The plugin validates:

• ✅ Phone number format (international format)
• ✅ Target point existence
• ✅ Required fulfillment data

Error Handling

The plugin provides detailed error messages for:

• Invalid phone numbers
• Missing target points
• InPost API errors
• Validation failures

Migration from v1

This plugin is designed for Medusa v2 and is not compatible with v1. If you're migrating from the v1 plugin (medusa-fulfillment-inpost), you'll need to:

1. Update your Medusa installation to v2
2. Replace the v1 plugin with this v2 version
3. Update your configuration as shown above
4. Test your integration thoroughly

Contributing

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

Support

If you need help with implementation or have questions, please:

• Open an issue on GitHub
• Contact us at SpearDevs

License

MIT License - see LICENSE file for details

Changelog

v0.1.0

• Initial release for Medusa v2
• InPost fulfillment provider
• Admin and Store API endpoints
• Phone number and point validation
• TypeScript support