Connect a channel

POST /channel_connections runs the same connect flow as the Nembol dashboard, on the next free slot for that channel. A second eBay account becomes a second channel account. Your key needs the channels:connect scope.

OAuth channels: send the merchant a link

eBay, Etsy, Shopify, WooCommerce, TikTok Shop, Temu, Amazon, Google Merchant Center, Facebook Catalog, Square, Squarespace, Faire, Wix, Facebook, Pinterest and Tumblr need the merchant to log in on the channel and approve Nembol. You get a single-use link, valid 1 hour:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "shopify", "params": {"shop": "acme-vintage"},
       "return_url": "https://app.example.com/nembol/callback?user=42"}'

{
  "id": "conn_66f0a1",
  "object": "channel_connection",
  "status": "pending",
  "connect_url": "https://api.nembol.com/rest/v1/connect/…",
  "expires_at": "2026-10-07T16:00:00.000Z"
}

Open connect_url in the merchant's browser. When they're done they land on your return_url with the outcome added to its query string:

https://app.example.com/nembol/callback?user=42&connection_id=conn_66f0a1&status=connected&channel_account_id=chac_6aa12cab

A link that can't be used also comes back to your return_url: expired (status=expired&error=link_expired), already used (the current status and error=link_already_used), or refused (status=failed and the reason, e.g. plan_not_eligible). Show your own message and create a new link if needed. The seller never sees a Nembol error page.

Don't trust the query string alone. Confirm with GET /channel_connections/{id} (connected / failed / expired) or the channel_account.connected webhook.

AI agents and scripts: leave return_url out. The merchant ends on a Nembol page saying they can close the tab, and the agent polls the connection.

Register your return URLs first

return_url must start with a URL registered for the store. This protects against using Nembol's login flow to send people to arbitrary sites:

curl -X POST https://api.nembol.com/rest/v1/redirect_urls \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/nembol/callback"}'

Same origin + a path starting with the registered one matches; any query string is allowed. The merchant can also manage the list in Settings → Developers → Redirect URLs.

Channels with API keys: connect at once

Kaufland, OnBuy, PrestaShop and Subito connect with credentials, and the response is already connected or failed:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "kaufland", "params": {"client_key": "…", "secret_key": "…"}}'

The keys are passed to the channel and never stored on the connection.

Channels that ask which account to connect

Amazon, Google Merchant Center and Facebook Catalog connect with a link like the others. After the login the seller may have several accounts to choose from (several Merchant Center accounts, several businesses). The connection then becomes needs_choice, its choices list the options, and you finish it with POST /channel_connections/{id}/choose and the chosen value. With a single option Nembol picks it and the connection is connected directly.

Disconnect

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/disconnect \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Disconnecting stops all sync with that account and can't be undone through the API (reconnecting needs the merchant's login again), so it asks for a confirmation first:

1. The first request answers 409 confirmation_required with a description of the consequences and a confirmation.token.
2. Show the consequences to the merchant. If they agree, repeat the same request with the header Nembol-Confirmation: <token>. The token works once and expires after 10 minutes.

See Confirmations and undo.

After connecting: imports and sync switches

Through the API a new connection imports nothing: your app owns the catalog. Ask for what you need when you create the connection:

New orders are synced from the moment the account is connected, whatever you choose. (The dashboard always imports both: the seller wants to see their shop at once.) You can also import later with POST /imports.

A newly connected account has every sync switch off: Nembol edits don't reach the channel and the channel's sales don't change stock elsewhere until you turn them on with PATCH /channel_accounts/{id}. See Edit a product: what reaches the channels.

eBay: Business Policies

To publish on eBay the account must use eBay Business Policies (every listing carries shipping, payment and return policies). Most sellers already do. Connecting never changes this, because enrolling moves the seller's eBay account for good. If the account isn't enrolled, eBay refuses the first publish; enable it explicitly, with the seller's agreement:

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/enable_business_policies \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

It asks for the two-step confirmation. The answer is ready (policies set, publishing works) or pending (eBay is migrating the account: call again in a few minutes). An account already enrolled answers ready and nothing changes.

Disconnect, then connect the same shop again

A disconnected account keeps its place with the name of its last shop, so its listings can find it again. The next POST /channel_connections for that channel brings it back: the answer has reconnects_shop (the shop it had), and the seller logs into that same shop.

• To connect a different shop instead, send "new_account": true: it takes a new place.
• If the seller logs into another shop without new_account, the connection fails with different_channel_account and nothing changes.

Reconnect an expired login

A marketplace login can expire or be revoked (a changed password, an app removed on the channel). The account then shows errors and stops syncing. To fix it without the dashboard, reconnect that same account:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel_account_id": "chac_6aa12cab",
       "return_url": "https://app.example.com/nembol/callback"}'

It works like a new connection (a connect_url for the seller, then return_url), with three differences:

• The account keeps its id (chac_…) and every listing linked to it; no new channel account is created and no free slot is needed.
• If the seller logs into a different shop or account than the one being reconnected, nothing changes and the connection fails with different_channel_account.
• channel is optional; when sent it must be the account's channel.

Same rules as the dashboard

The API runs the dashboard's own connect flow, so every Nembol rule applies. Nothing an integration does can go beyond what the merchant could do in Nembol:

• One marketplace account, one Nembol store. An eBay (Etsy, Shopify…) account already connected to any Nembol store can't be connected again; the connection ends failed with the channel's message.
• Active subscription required, checked like the dashboard does (including a live check with the payment provider): otherwise 402 subscription_inactive.
• The account the store pays Nembol through (Shopify, WooCommerce or Wix billing) can't be disconnected: 422 channel_not_disconnectable.
• Everything is checked again when the link is opened. If the slot was taken meanwhile, the plan changed or the subscription lapsed, the link is refused and the connection ends failed.

Gotchas

• One link, one use. An opened or expired link can't be reused. Create a new connection.
• Expired login vs disconnected account. An account whose login expired still exists: reconnect it with channel_account_id (it keeps its id). An account that was disconnected comes back with the next connection of that channel (same place and listings, a new chac_ id: the old id answers 404 channel_account_not_found and its listings now carry the new id in channel_account_id); see above.
• Etsy, second shop: the merchant must be signed out of the first shop on etsy.com before opening the link, or Etsy will sign them into the same shop again.
• Slots fill up. Each channel has a limited number of accounts per store: 422 channel_slots_full means disconnect one first.
• Plan limits apply like in the dashboard: 403 plan_channel_not_included when the plan doesn't include the channel.
• No automatic import through the API. A connection made from the dashboard starts the usual first import; one made through the API imports only what import_products / import_orders ask for.

Last updated on October 18, 2026