Connectors
Installing a connector, mapping the catalog, running a dry sync, and keeping the mapping alive as channels change underneath you.
On this page
A connector is the adapter between the hub and one external system. It handles authentication, field mapping, scheduling and the channel's own error vocabulary. Installing one is a five-step job, and four of those steps are mapping.
Install and authorise
Connectors are installed per project, so two brands can connect to the same marketplace with separate credentials and separate mappings.
OAuth where the channel supports it, API credentials where it does not. Credentials are stored encrypted and are never exposed back through the API or the interface once saved.
Match your categories to the channel taxonomy and your attributes to its required fields. The connector tells you which fields are mandatory before you sync, not after it rejects them.
Defaults are sensible — content and stock out, orders in — and every one of them is editable. See the table in How channels work.
A dry run produces the full list of creates, updates and rejections without writing anything. Read it. The first one is always instructive.
Mapping in practice
Mapping fails in three predictable ways, and all three are visible in a dry run:
- Required attribute missing — the channel wants a material, a hazard class or an age rating that your catalog does not carry. Add it as a product attribute rather than typing it into the listing, or you will type it again for every SKU.
- Taxonomy mismatch — your category maps to a channel node that no longer exists. Re-map the node; do not reorganise your own tree to match theirs.
- Unit and currency drift — grams against ounces, tax-inclusive against tax-exclusive. Set these per channel once, and verify with a single SKU before mapping the rest.
Scheduling and retries
Each connector declares what it can do — push, pull, or receive webhooks — and runs on its own schedule. Failures retry with exponential backoff and land in a dead-letter queue you can inspect and replay per record.
| State | Meaning | What to do |
|---|---|---|
healthy | Last run completed, queue drained | Nothing |
degraded | Retrying, queue growing | Check the channel's status page |
stale | No successful run in the expected window | Re-authorise; tokens expire quietly |
blocked | Channel rejected the credentials or the account | Fix at the channel, then replay |
Building your own
The plugin system is the same surface our own connectors use — there is no privileged internal path. A connector registers itself, declares its capabilities and implements the handlers it needs.
registerPlugin({
id: 'acme-marketplace',
capabilities: ['catalog.push', 'inventory.push', 'orders.pull'],
handlers: {
'catalog.push': async ({ listings, client }) => client.upsertListings(listings),
'orders.pull': async ({ since, client }) => client.fetchOrders({ since })
}
})
See Plugins for the lifecycle, configuration schema and testing approach.
Changing your mind
Disconnecting a channel stops sync and keeps the data. Listings become inactive, orders and their history stay exactly where they are, and the mapping is preserved so reconnecting later is not a fresh start.
Your catalog and order history export in full, in open formats, whenever you ask. That is deliberate: a platform should keep you because leaving is unattractive, not because it is difficult.
