syndicate-add-attribution

Original：🇺🇸 English
Translated

Install Syndicate Links conversion attribution using the shipped merchant API. Covers Shopify backends, generic checkouts, SaaS apps, webhook workers, and agent surfaces without relying on draft-only SDKs or CDN scripts.

1installs
Sourcecmcgrabby-hue/attribution-skills
Added on

NPX Install

npx skill4agent add cmcgrabby-hue/attribution-skills syndicate-add-attribution

Tags

Translated version includes tags in frontmatter
syndicate-linksconversion-attributionmerchant-apiserver-side-integrationshopify-integration

SKILL.md Content

View Translation Comparison →

Syndicate Links Attribution Install

Use this skill when a merchant needs to report orders into Syndicate Links attribution.
The live rail is server-side conversion reporting:
http
POST https://api.syndicatelinks.co/merchant/conversions
Authorization: Bearer mk_live_...
This skill intentionally omits draft-only browser SDK, CDN snippet, and CLI verification paths. Use the authenticated merchant API only.

Prerequisites

  • A Syndicate Links merchant account
  • A merchant API key with 
    conversions:fire
    scope
  • A valid Syndicate Links tracking code for the affiliate or agent link being credited
  • Server-side access to the order completion path
Never put a merchant API key in browser JavaScript, Liquid templates, mobile apps, or public repos.

1. Identify the conversion boundary

Pick the backend point that runs once per completed order:
  • Shopify: order status webhook, server app, or Shopify Function/backend worker
  • Generic checkout: server-side success handler or payment webhook
  • SaaS app: backend route called after payment succeeds
  • Agent or MCP surface: server process that knows the selected tracking code
The implementation is the same for every surface: collect order data server-side, then call 
POST /merchant/conversions
.

2. Capture the tracking code

Syndicate Links conversion fire expects 
trackingCode
, not 
publisherCode
.
Common sources:
  • Tracking link code returned by 
    POST /affiliate/links
  • Code stored when the buyer entered through a Syndicate Links click URL
  • Code supplied by an approved agent publisher flow
Persist the tracking code with the cart, checkout session, customer session, or order metadata so the backend can access it after payment completes.

3. Fire the conversion

bash
curl -sS -X POST https://api.syndicatelinks.co/merchant/conversions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingCode": "trk_abc123",
    "orderId": "order_123",
    "saleAmount": 99.99,
    "currency": "USD"
  }' | python3 -m json.tool
Optional fields supported by the implementation include 
clickId
and 
items
when your system has them. Keep 
orderId
stable and unique.
A successful response is 
201 Created
with a conversion event, commission information, attribution metadata, and tracking fee details.

4. Verify recent conversions

bash
curl -sS "https://api.syndicatelinks.co/merchant/conversions?limit=5" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
Look for:
  • The expected 
    orderId
  • saleAmount
    matching the order total
  • status
    of 
    pending
    or 
    confirmed
  • affiliateId
    populated
  • attributionMethod
    set, usually 
    tracking_code
    unless a click match upgraded it

Platform notes

Shopify

Do not paste merchant API keys into theme Liquid. Use an authenticated backend app, order webhook, or server function. Store the tracking code in order metadata if you capture it before checkout.

Generic checkout

Call the conversion endpoint from the payment success webhook or server success route. Do not call it from a browser thank-you page.

SaaS apps

Call the conversion endpoint from your backend payment handler, for example a Stripe, Paddle, Chargebee, or Lemon Squeezy webhook worker.

Agent surfaces

If an AI agent can choose or recommend a merchant link, have it pass the selected tracking code to the merchant server. The merchant server still performs the authenticated conversion fire.

Common pitfalls

  1. Wrong endpoint. Use 
    https://api.syndicatelinks.co/merchant/conversions
    with no version prefix.
  2. Wrong amount field. The API expects 
    saleAmount
    , not 
    amount
    .
  3. Wrong attribution field. The API expects 
    trackingCode
    , not 
    publisherCode
    .
  4. Client-side secrets. Merchant API keys must stay server-side.
  5. Duplicate order IDs. Reusing 
    orderId
    can cause reporting and reconciliation drift.

Links