Marketplace Adapters

Overview

NexusCommerce integrates with seven marketplaces through a unified adapter architecture. Each adapter translates between NexusCommerce's internal data model and the marketplace's native API, handling authentication, rate limiting, error recovery, and field mapping.

All adapters live in the packages/marketplace-adapters package and expose a consistent interface to the NestJS API layer.

Key Concepts

Adapter Interface — Every adapter implements the same TypeScript interface:

interface MarketplaceAdapter {
  // Authentication
  testConnection(credentials: Credentials): Promise<ConnectionTestResult>
  refreshToken(credentials: Credentials): Promise<Credentials>

  // Catalog
  listProducts(params: ListParams): Promise<PaginatedResult<Product>>
  getProduct(id: string): Promise<Product>
  createProduct(product: Product): Promise<string>
  updateProduct(id: string, product: Partial<Product>): Promise<void>

  // Orders
  listOrders(params: ListParams): Promise<PaginatedResult<Order>>
  getOrder(id: string): Promise<Order>
  confirmShipment(orderId: string, shipment: Shipment): Promise<void>

  // Inventory
  updateInventory(items: InventoryUpdate[]): Promise<void>
  getInventory(skus: string[]): Promise<InventoryLevel[]>

  // Pricing
  updatePrice(items: PriceUpdate[]): Promise<void>

  // Webhooks (optional)
  registerWebhook?(url: string, events: string[]): Promise<void>
  verifyWebhook?(payload: Buffer, signature: string): boolean
}

Rate Limiting — Each adapter implements marketplace-specific rate limit handling. The adapter tracks request quotas and uses exponential backoff when throttled. Rate limit state is stored in Redis so multiple worker instances share the same quota tracking.

Credential Storage — Marketplace credentials (API keys, OAuth tokens, refresh tokens) are stored encrypted in Supabase's marketplace_connections table. The encryption key is set in the CREDENTIALS_ENCRYPTION_KEY environment variable.

Field Mapping — Each marketplace uses different field names, data types, and category taxonomies. Adapters handle bidirectional mapping: NexusCommerce format → marketplace format (for writes) and marketplace format → NexusCommerce format (for reads).

Getting Started

Adapters are used automatically when you create a Marketplace Connection. You do not interact with adapters directly unless you are developing a custom integration.

To add a new marketplace connection, see First Connection.

Supported Marketplaces

Features

Adapter Configuration

Each adapter can be configured with connection-level settings passed in the config field of the marketplace_connections record:

{
  "sync_interval_minutes": 60,
  "order_lookback_days": 30,
  "inventory_buffer_pct": 10,
  "marketplace_id": "ATVPDKIKX0DER",
  "storefront": "de"
}

Error Handling

All adapters implement a consistent error hierarchy:

Custom Adapters

To add support for a new marketplace, implement the MarketplaceAdapter interface and register the adapter in the AdapterRegistry:

// packages/marketplace-adapters/src/registry.ts
import { MyMarketplaceAdapter } from './my-marketplace/adapter'

AdapterRegistry.register('my_marketplace', MyMarketplaceAdapter)

See the existing adapter implementations for reference. The Shopify adapter is the most readable starting point.

Configuration

Global adapter settings are in the .env file: