Connections
Manage marketplace integrations, sync schedules, and credential health.
Overview
The Connections page is the control panel for all marketplace integrations. Each connection represents an authenticated link to one marketplace account. From here you can add new connections, view sync history, diagnose errors, and configure sync schedules.
Key Concepts
Adapter — The code layer that translates between NexusCommerce's internal API and a marketplace's native API. Each marketplace has a dedicated adapter in the packages/marketplace-adapters package.
Connection Health — A computed score based on the last N sync cycles. A healthy connection has 100% successful syncs. A degraded connection has intermittent failures. An unhealthy connection has consecutive failures.
Sync Cycle — One complete pass of the adapter: fetch updates, normalize records, upsert to Supabase, push inventory changes back to the marketplace. The duration of a sync cycle varies by catalog size and marketplace API rate limits.
Rate Limiting — Marketplaces impose API rate limits. Adapters implement exponential backoff and respect Retry-After headers. The connection status shows rate_limited when the adapter is waiting before retrying.
Getting Started
Navigate to Connections in the left sidebar. If you have not added any connections yet, the page shows an empty state with a prompt to add your first connection.
To add a connection:
- Click Add Connection
- Select a marketplace from the grid
- Enter the required credentials (see First Connection for per-marketplace credential details)
- Click Test Connection
- If the test passes, click Save
- Click Sync Now on the new connection card to trigger the initial import
Features
Connection Cards
Each connection is displayed as a card on the Connections page:
- Marketplace logo and name
- Account identifier (seller name or shop domain)
- Status badge (active / error / rate_limited / pending)
- Last sync time
- Next scheduled sync time
- Quick stats: products synced, orders today
Actions on each card:
| Action | Description |
|---|---|
| Sync Now | Trigger an immediate full sync |
| Edit Credentials | Update API keys or tokens |
| Reconnect | Re-run the OAuth flow for token refresh |
| View Sync Log | Open the sync history modal |
| Pause | Pause the scheduled sync (useful for maintenance) |
| Remove | Delete the connection (does not delete synced data) |
Sync History
Click View Sync Log on any connection card to open the sync history. Each sync cycle is recorded with:
- Start and end timestamp
- Duration
- Records processed (products, orders, inventory)
- Status (success / partial / failed)
- Error details (if failed)
Expandable rows show the raw error response from the marketplace API.
Error Diagnostics
When a connection enters error status, the card shows an inline error summary. Common errors and resolutions:
| Error | Cause | Resolution |
|---|---|---|
Token expired | OAuth access token has expired | Click Reconnect to re-run the OAuth flow |
Invalid credentials | API key or secret is incorrect | Click Edit Credentials and re-enter |
Marketplace unavailable | Marketplace API is down | Wait; the adapter retries automatically |
Account suspended | Seller account is suspended on the marketplace | Resolve suspension in the marketplace seller portal |
Scope missing | The OAuth app lacks required permissions | Re-authorize with the correct scope set |
Per-Connection Sync Settings
Click Edit on a connection card to access per-connection settings:
| Setting | Options | Description |
|---|---|---|
| Sync interval | 15m, 1h, 4h, daily | How often the adapter polls |
| Sync window | Time range | Restrict polling to business hours (useful for rate limit management) |
| Order lookback | 7d, 30d, 90d, 1y | How many days of historical orders to include |
| Inventory buffer | 0–50% | Per-connection safety stock override |
| Auto-reconnect | On / Off | Automatically re-run OAuth when tokens expire |
Webhook Registration
For marketplaces that support webhooks (Shopify, eBay), the connection detail page shows registered webhook endpoints:
POST https://your-nexuscommerce.com/api/webhooks/shopify/conn_abc123
POST https://your-nexuscommerce.com/api/webhooks/ebay/conn_xyz789Webhook payloads are verified using the marketplace's signature mechanism before processing.
Multi-Account Support
You can connect multiple accounts from the same marketplace. Example: one Amazon US seller account and one Amazon EU seller account. Each connection is independent with its own credentials, sync schedule, and data.
On the Products and Orders lists, a connection filter allows you to scope views to a specific marketplace account.
Configuration
Global connection settings are in Settings > General > Connections:
| Setting | Description |
|---|---|
| Default sync interval | Applied to new connections |
| Retry attempts | Number of retries before marking a sync as failed |
| Retry backoff | Initial backoff delay for failed requests |
| Webhook secret rotation | Frequency for rotating webhook signing secrets |
| Connection alert cooldown | Minimum time between alerts for the same connection error |