Quick Start

1. Installation

# npm
npm install @u11d/medusa-base

# yarn
yarn add @u11d/medusa-base

2. Configuration

Add the plugin to your medusa-config.ts:

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

export default defineConfig({
  plugins: [
    {
      resolve: "@u11d/medusa-base",
      options: {
        api_key: process.env.BASE_API_KEY,
        order_status_id: parseInt(process.env.BASE_ORDER_STATUS_ID || "1"),
        custom_source_id: parseInt(process.env.BASE_CUSTOM_SOURCE_ID || "1"),
      },
    },
  ],
});

3. Environment Variables

Add to your .env file:

BASE_API_KEY=your_base_api_key_here
BASE_ORDER_STATUS_ID=1  # Default order status in Base.com
BASE_CUSTOM_SOURCE_ID=1 # Custom source ID for orders

4. Run Database Migration

After configuring your Medusa setup, run the database migration to create the required tables:

npx medusa db:migrate

This creates the following helper tables:

• base_location - Maps Base.com warehouse IDs to Medusa stock location IDs
• base_product_variant - Maps Base.com product/variant IDs to Medusa product variant IDs

5. Start Your Server

npm run dev

Configuration Options

Access your Base.com dashboard to obtain the required API credentials

| Option | Type | Required | Default | Description | | ------------------ | -------- | -------- | ------- | ----------------------------------------------- | | api_key | string | ✅ | - | Your Base.com API key | | order_status_id | number | ✅ | 1 | Default order status ID in Base.com | | custom_source_id | number | ✅ | 1 | Custom source ID for orders created in Base.com |

Usage

Product Synchronization

The syncProductsWorkflow synchronizes products from Base.com to Medusa, including:

• Product information (title, description, images)
• Product variants
• Pricing
• Stock levels across warehouses

Manual Sync via API

Trigger product synchronization manually via API:

POST /admin/base/products

Example:

curl -X POST http://localhost:9000/admin/base/products \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json"

Scheduled Sync

Create a scheduled job in src/jobs/sync-base-products.ts:

import type { MedusaContainer } from "@medusajs/framework/types";
import { syncProductsWorkflow } from "@u11d/medusa-base/workflows";

export default async function syncBaseProducts(container: MedusaContainer) {
  await syncProductsWorkflow(container).run();
}

export const config = {
  name: "sync-base-products",
  schedule: "0 */6 * * *", // Every 6 hours
};

Order Creation

Orders are automatically created in Base.com when placed in Medusa. The createBaseOrderWorkflow is triggered automatically via the order.placed event.

No additional configuration needed - the subscription is registered by the plugin.

Order Creation Flow:

1. Fetches the Medusa order details
2. Maps Medusa products to Base.com products using helper entities
3. Creates the order in Base.com with configured status and source

Troubleshooting

Migration Error: "relation ... does not exist"

If you encounter errors about missing tables:

relation "base_product_variant" does not exist
relation "base_location" does not exist

Solution: Run the database migration:

npx medusa db:migrate

Product Sync Issues

If products are not syncing correctly:

1. Check application logs for any error messages related to Base.com API calls
2. Verify API credentials in your .env file
3. Check Base.com inventory - ensure products exist in your Base.com account
4. Test API connection - verify your API key has proper permissions in Base.com dashboard
5. Review Base.com API limits - ensure you're not hitting rate limits

Order Creation Failures

If orders are not being created in Base.com:

1. Verify order_status_id exists in your Base.com account
2. Check custom_source_id is configured correctly
3. Ensure product mapping - verify products were synced and exist in base_product_variant table
4. Review order logs - check Medusa logs for detailed error messages
5. Test Base.com order creation - try creating an order manually in Base.com to verify permissions

Need Help?

If you encounter any issues or need assistance with this plugin, please visit our GitHub Issues page. Our team actively monitors and responds to bug reports, feature requests, and questions from the community. We aim to provide timely support to ensure your integration with Base.com runs smoothly.

Need expert assistance or want our team to support your Medusa project? We're here to help! Contact us at https://u11d.com/contact/ for professional support and consultation services.