medusa-amazon

Medusa v2 plugin that integrates Amazon SP-API for admin operations, data retrieval, and Amazon-to-Medusa sync flows.

Plugin Overview

medusa-amazon connects a Medusa backend to Amazon Selling Partner API (SP-API) and exposes:

• Admin API routes for Amazon orders, listings, inventory, pricing, catalog, reports, finance, and seller marketplaces.
• Sync routes that import Amazon listings into Medusa products and Amazon orders into Medusa orders.
• Admin extension pages under an Amazon section for operational usage.

It solves the need to centrally operate Amazon marketplace data from Medusa without building custom SP-API wiring in each project.

Medusa Version

• Built for Medusa v2 (uses @medusajs/framework, @medusajs/medusa, and Medusa v2 module/core-flow patterns).

Installation & Setup

1) Install package

npm install medusa-amazon

yarn add medusa-amazon

2) Register plugin in medusa-config.ts

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

export default defineConfig({
  plugins: [
    {
      resolve: "medusa-amazon",
      options: {
        client_id: "<amazon_lwa_client_id>",
        client_secret: "<amazon_lwa_client_secret>",
        refresh_token: "<amazon_lwa_refresh_token>",
        aws_access_key: "<aws_access_key_id>",
        aws_secret_key: "<aws_secret_access_key>",
        role_arn: "<aws_role_arn_for_assume_role>",
        seller_id: "<amazon_seller_id>",
        marketplace_id: "<amazon_marketplace_id>",
        region: "eu-west-1",
        endpoint: "https://sellingpartnerapi-eu.amazon.com",
        sandbox: false,
      },
    },
  ],
})

3) Build / run

npx medusa plugin:build
npx medusa develop

4) Database migrations

This plugin does not define custom entities/migrations, so no plugin-specific migration command is required.

Configuration (config.ts / plugin options)

Plugin options type is defined in src/types/index.ts as AmazonPluginOptions, and required keys are validated in src/modules/amazon-sp/service.ts.

| Option | Type | Required | Default | Description | |---|---|---|---|---| | client_id | string | Yes | - | Amazon LWA app client ID. | | client_secret | string | Yes | - | Amazon LWA app client secret. | | refresh_token | string | Yes | - | LWA refresh token used to obtain access tokens. | | aws_access_key | string | Yes | - | AWS access key for STS AssumeRole. | | aws_secret_key | string | Yes | - | AWS secret key for STS AssumeRole. | | role_arn | string | Yes | - | IAM role ARN assumed before signing SP-API requests. | | seller_id | string | Yes | - | Seller ID used in listings APIs. | | marketplace_id | string | Yes | - | Marketplace ID used in SP-API calls. | | region | string | No | eu-west-1 | AWS region for STS + SigV4 signing. | | endpoint | string | No | EU production host | Optional SP-API host override. | | sandbox | boolean | No | false | If true, uses sandbox EU host. |

Complete config block

{
  resolve: "medusa-amazon",
  options: {
    client_id: "amzn-client-id",
    client_secret: "amzn-client-secret",
    refresh_token: "Atzr|...",
    aws_access_key: "AKIA...",
    aws_secret_key: "....",
    role_arn: "arn:aws:iam::<account-id>:role/<role-name>",
    seller_id: "A1EXAMPLESELLER",
    marketplace_id: "A1PA6795UKMFR9",
    region: "eu-west-1",
    endpoint: "https://sellingpartnerapi-eu.amazon.com",
    sandbox: false,
  },
}

Environment Variables

No process.env.* references are used directly in implemented plugin source files under src.

| Variable | Required | Purpose | Example | |---|---|---|---| | None in implementation | - | - | - |

⚠️ Note: Environment variables are typically consumed in your Medusa app and mapped into plugin options. This plugin code itself only reads options, not process.env.

REST APIs / Routes

Base admin path: /admin/amazon

Amazon admin routes

| Method | Path | Auth | Query / Body | Response | |---|---|---|---|---| | GET | /admin/amazon/orders | Admin route | Query: createdAfter, createdBefore, status, maxResults, nextToken (requires either time filter or nextToken) | { orders, nextToken? } | | GET | /admin/amazon/orders/:orderId | Admin route | Path orderId | { order } | | GET | /admin/amazon/orders/:orderId/items | Admin route | Path orderId | { items } | | GET | /admin/amazon/listings | Admin route | Query: pageToken, pageSize | { listings, nextToken? } | | GET | /admin/amazon/listings/:sku | Admin route | Path sku | Listing payload | | DELETE | /admin/amazon/listings/:sku | Admin route | Path sku | Amazon delete response | | GET | /admin/amazon/inventory | Admin route | Query: nextToken, sellerSkus, startDateTime | { inventories, nextToken? } | | GET | /admin/amazon/catalog/search | Admin route | Query: keywords, pageToken | { items, nextToken? } | | GET | /admin/amazon/catalog/:asin | Admin route | Path asin | Catalog item payload | | GET | /admin/amazon/pricing/asin | Admin route | Query required: asins (comma-separated) | { payload } | | GET | /admin/amazon/pricing/sku | Admin route | Query required: skus (comma-separated) | { payload } | | GET | /admin/amazon/pricing/competitive | Admin route | Query required: asins (comma-separated) | { payload } | | POST | /admin/amazon/reports | Admin route | Body: reportType, marketplaceIds, optional dataStartTime, dataEndTime, reportOptions | { reportId } | | GET | /admin/amazon/reports/:reportId | Admin route | Path reportId | Report status payload | | GET | /admin/amazon/finance/event-groups | Admin route | Query: startAfter, startBefore, nextToken, maxResults | { payload } | | GET | /admin/amazon/finance/orders/:orderId | Admin route | Path orderId | { events } | | GET | /admin/amazon/seller/marketplaces | Admin route | - | { payload } | | POST | /admin/amazon/sync/products | Admin route | Body: none | { synced, errors } | | POST | /admin/amazon/sync/orders | Admin route | Body optional: { daysBack?: number } | { synced, errors } |

Plugin health routes

| Method | Path | Auth | Response | |---|---|---|---| | GET | /admin/plugin | Admin route context | 200 | | GET | /store/plugin | Public store route | 200 |

Important endpoint examples

curl -X GET "http://localhost:9000/admin/amazon/orders?createdAfter=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

curl -X GET "http://localhost:9000/admin/amazon/pricing/asin?asins=B012345678,B087654321" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

curl -X POST "http://localhost:9000/admin/amazon/reports" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
    "marketplaceIds": ["A1PA6795UKMFR9"]
  }'

curl -X POST "http://localhost:9000/admin/amazon/sync/orders" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"daysBack": 7}'

Services

1) AmazonSpModuleService

Location: src/modules/amazon-sp/service.ts

Purpose: core SP-API integration service (orders, listings, catalog, inventory, pricing, reports, finance, seller).

Key methods (selected):

| Method | Description | |---|---| | getOrders(params) | Fetches paged Amazon orders. | | getAllOrders(params) | Iterates all order pages by NextToken. | | getOrder(orderId) / getOrderItems(orderId) | Gets order detail and item lines. | | getListings(params) / getAllListings() / getListing(sku) / deleteListing(sku) | Listing retrieval and deletion. | | searchCatalogItems(params) / getCatalogItem(asin) | Catalog search and item detail retrieval. | | getInventory(params) / getAllInventory() | FBA inventory retrieval. | | getPricingByASIN(asins) / getPricingBySKU(skus) / getCompetitivePricing(asins) | Pricing APIs. | | createReport(request) / getReport(reportId) / getReports(params) / getReportDocument(reportDocumentId) | Reports APIs. | | getFinancialEventGroups(params) / getFinancialEventsByOrder(orderId) | Finance data retrieval. | | getMarketplaceParticipations() | Seller marketplace participation info. |

2) AmazonSyncModuleService

Location: src/modules/amazon-sync/service.ts

Purpose: imports Amazon data into Medusa using Medusa core workflows.

Key methods:

| Method | Description | |---|---| | syncProducts(container) | Imports listings, creates/updates Medusa products and variants, maps metadata (amazon_sku, amazon_asin, etc.). | | syncOrders(container, daysBack) | Imports Amazon orders into Medusa orders, de-duplicates by metadata.amazon_order_id, maps buyer/address/items. |

3) AmazonAuth utility

Location: src/utils/amazon-auth.ts

Purpose: handles authentication/signing internals for SP-API.

Key methods:

| Method | Description | |---|---| | getAccessToken() | Exchanges LWA refresh token for access token (cached). | | getAWSCredentials() | Assumes IAM role via STS to obtain temporary credentials (cached). | | signedRequest(config) | Signs and sends SP-API requests (aws4 + axios), normalizes upstream errors. |

Workflows & Steps (Medusa v2)

This plugin does not define custom workflows/steps with createWorkflow/createStep.

It invokes Medusa core workflows inside sync service:

• createProductsWorkflow
• updateProductsWorkflow
• createOrderWorkflow

Subscribers / Event Hooks

No subscribers/event handlers are implemented.

Admin UI / Widgets

The plugin provides admin route extensions (not widget-zone injections), all under Amazon.

Admin hub route

• Location: Amazon item in sidebar.
• What it renders: hub page with navigation buttons to sub-pages.
• File: src/admin/routes/amazon/page.tsx

Admin sub-pages

| Route | What it renders | Interactions / Data | |---|---|---| | /amazon/orders | Order list + order detail/items fetch panels | Calls /admin/amazon/orders, /orders/:orderId, /orders/:orderId/items | | /amazon/listings | Listings table + SKU detail/delete actions | Calls /admin/amazon/listings, /listings/:sku | | /amazon/catalog | Keyword search + ASIN detail panel | Calls /admin/amazon/catalog/search, /catalog/:asin | | /amazon/inventory | Inventory query form + JSON response | Calls /admin/amazon/inventory | | /amazon/pricing | ASIN/SKU/competitive pricing actions | Calls /admin/amazon/pricing/* | | /amazon/finance | Event-group query + order financial events | Calls /admin/amazon/finance/* | | /amazon/reports | Create report + report status lookup | Calls /admin/amazon/reports | | /amazon/sync | Product sync + order sync actions | Calls /admin/amazon/sync/* | | /amazon/seller | Marketplace participations fetch | Calls /admin/amazon/seller/marketplaces |

Reusable UI helpers are in src/admin/components/amazon/* (api-client, loading/error/success/json components, toolbar/pagination helpers).

Models & Entities

No custom models/entities are defined by this plugin.

The plugin reads/writes Medusa core entities via query/workflows, including:

• product, product_variant
• order
• region, sales_channel, shipping_profile

and stores Amazon linkage fields in Medusa metadata (for example amazon_order_id, amazon_sku, amazon_asin).

Use Cases & Examples

1. Backoffice Amazon order monitoring

   • Use /admin/amazon/orders and /admin/amazon/orders/:orderId/items to inspect Amazon orders directly in Medusa admin.

2. Catalog/listing operations from Medusa

   • Use listings and catalog routes to inspect seller listings and ASIN details without leaving Medusa.

3. Competitive pricing checks

   • Use /admin/amazon/pricing/asin or /admin/amazon/pricing/competitive for price intelligence.

4. Periodic product sync into Medusa catalog

   • Trigger /admin/amazon/sync/products to create/update products and variants from Amazon listings.

5. Amazon order ingestion for unified operations

   • Trigger /admin/amazon/sync/orders to import recent Amazon orders into Medusa order records.

Troubleshooting

Missing required plugin options on startup

• Symptom: errors like Missing required option: client_id.
• Fix: provide all required options in plugin registration (client_id, client_secret, refresh_token, aws_access_key, aws_secret_key, role_arn, seller_id, marketplace_id).

Amazon orders route rejects request

• Symptom: /admin/amazon/orders returns invalid input asking for createdAfter or nextToken.
• Fix: include createdAfter (recommended) or pass valid nextToken.

LWA token or STS AssumeRole failures

• Symptom: errors containing LWA token request failed or STS AssumeRole failed.
• Fix: verify Amazon app credentials, refresh token, AWS key pair, role ARN trust/policies, and region alignment.

Sync returns zero with configuration error

• Symptom: sync response includes missing default region/sales channel/shipping profile error.
• Fix: ensure your Medusa store has at least one region, sales_channel, and shipping_profile configured.

SP-API request rejected by Amazon

• Symptom: error message with Amazon error code/details.
• Fix: validate query/body fields, marketplace scope, permissions for the API family (orders/listings/reports/etc.), and try the same request with narrowed parameters.