Base.com

Medusa Base.com Plugin

Quick Start

1. Installation

12345
# npm
npm install @u11d/medusa-base

# yarn
yarn add @u11d/medusa-base

2. Configuration

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

1234567891011121314
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 Copy to clipboard.env file:

123
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:

1
npx medusa db:migrate

This creates the following helper tables:

• Copy to clipboardbase_location - Maps Base.com warehouse IDs to Medusa stock location IDs
• Copy to clipboardbase_product_variant - Maps Base.com product/variant IDs to Medusa product variant IDs

5. Start Your Server

1
npm run dev

Configuration Options

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

Option Type Required Default Description Copy to clipboardapi_key Copy to clipboardstring ✅ - Your Base.com API key Copy to clipboardorder_status_id Copy to clipboardnumber ✅ Copy to clipboard1 Default order status ID in Base.com Copy to clipboardcustom_source_id Copy to clipboardnumber ✅ Copy to clipboard1 Custom source ID for orders created in Base.com

Usage

Product Synchronization

The Copy to clipboardsyncProductsWorkflow 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:

1
POST /admin/base/products

Example:

123
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 Copy to clipboardsrc/jobs/sync-base-products.ts:

1234567891011
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 Copy to clipboardcreateBaseOrderWorkflow is triggered automatically via the Copy to clipboardorder.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:

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

Solution: Run the database migration:

1
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 Copy to clipboard.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 Copy to clipboardorder_status_id exists in your Base.com account
2. Check Copy to clipboardcustom_source_id is configured correctly
3. Ensure product mapping - verify products were synced and exist in Copy to clipboardbase_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.