---
name: syndicate-fire-conversion
description: Fire a conversion event against a Syndicate Links tracking code. Commission is auto-calculated from program settings. Idempotent on order_id.
version: 0.1.0
---

# syndicate-fire-conversion

## When to use

When a purchase (or equivalent conversion event) completes and you need to attribute it to the publisher who referred the customer.

## Inputs

- `tracking_code` (required) — the short code from the tracking link (e.g., `GY7i_Nc6`)
- `amount_cents` (required) — sale amount in integer cents
- `order_id` (optional) — your order identifier. Providing this makes the call idempotent — duplicate POSTs return the original conversion, they don't double-count.
- `currency` (optional, default `"usd"`)
- `metadata` (optional) — freeform JSON, returned on conversion lookup

## Output

```json
{
  "id": "cv_...",
  "status": "pending",
  "amount_cents": 10000,
  "commission_cents": 1000,
  "publisher_id": "pub_...",
  "program_id": "p_...",
  "tracking_link_code": "GY7i_Nc6",
  "order_id": "order_456",
  "created_at": "2026-04-18T..."
}
```

## Procedure

1. `POST /merchant/conversions` with body above, `Authorization: Bearer mk_live_...`
2. Check response `status` — `pending` is the initial state; it flips to `approved` after the program's review window (default 7 days) unless you refund or dispute it via `POST /merchant/refunds`.

## Auth

Requires `conversions:write` scope (or a wildcard `*` key).

## Idempotency

`order_id` + `tracking_code` is the dedup key. Replaying the same request returns `200` with the original conversion body. Different `order_id` = different conversion, even for the same tracking code.

## Error handling

- `404 tracking code not found` → the publisher link may have been revoked, or the code is wrong. Do not retry blindly.
- `409 duplicate order` → idempotent hit; treat as success, log the returned conversion id.
- `422 partnership not approved` → the publisher/merchant partnership is in `pending` state. Conversion is queued; no action needed.

## Docs

Full API: https://syndicatelinks.co/docs/agent-integration