syndicate-merchant-onboard

When to use

When a merchant asks (or an orchestrating agent decides) to set up affiliate tracking on Syndicate Links without touching the dashboard.

Inputs

• business_name (required) — the merchant's company name
• description (required) — one-line description of what they sell
• url (required) — storefront or primary product URL
• email (required) — contact email for the merchant account
• commission_pct (optional, default "10.00") — commission rate as a string percent
• products (optional) — array of {name, url, price, external_id?}. Default: one placeholder pointing at url.

Outputs

{
  "merchant_id": "m_...",
  "api_key": "mk_live_...",
  "program_id": "p_...",
  "product_ids": ["pr_..."],
  "tracking_links": [{"tracking_code": "...", "click_url": "https://api.syndicatelinks.co/click/..."}],
  "wall_clock_seconds": 8.3
}

Procedure

1. POST /merchant/register with company + email + password → get merchant_id and api_key. No CAPTCHA, no verification gate.
2. POST /merchant/programs with name, commission_pct, description.
3. For each product: POST /merchant/products with program_id, name, url, price, optional external_id.
4. For each product: POST /merchant/test-links with program_id + product_id → {code, clickUrl}.
5. (Optional) POST /merchant/webhooks for conversion/payout events.
6. (Optional demo) POST /merchant/conversions with tracking_code + amount_cents.

Reference implementation

Python SDK: https://github.com/syndicate-links/syndicate-links/blob/master/examples/setup_agent.py

Error handling

• 429 → back off with exponential jitter; plan limits are generous (see https://syndicatelinks.co/pricing)
• 400 on register with "slug already exists" → retry with a suffixed business name or let the server auto-suffix
• 422 on product create → verify program_id ownership and that price is a decimal string

Auth

Returned api_key is wildcard-scoped (["*"]) by default. For narrower automation, immediately mint a scoped key: POST /merchant/api-keys {"name":"automation","scopes":["conversions:write","analytics:read"]} and discard the initial wildcard key.