---
name: syndicate-merchant-onboard
description: Cold-onboard a merchant to Syndicate Links end-to-end — register account, create affiliate program, add products, generate tracking links, fire demo conversion. Under 10 minutes.
version: 0.1.0
---

# 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

```json
{
  "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.