Back to Details

syndicate-add-attribution

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syndicate Links Attribution Install

Syndicate Links 转化归因安装指南

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.
当商家需要将订单数据上报至Syndicate Links归因系统时，可使用本技能。
当前主流方案是服务器端转化上报：
http
POST https://api.syndicatelinks.co/merchant/conversions
Authorization: Bearer mk_live_...
本技能刻意省略了仅草稿版的浏览器SDK、CDN代码片段以及CLI验证路径，仅使用经过认证的商家API。

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.
  • 拥有Syndicate Links商家账户
  • 具备
    conversions:fire
    权限范围的商家API密钥
  • 用于关联联盟或Agent链接的有效Syndicate Links追踪码
  • 可访问订单完成路径的服务器端权限
切勿将商家API密钥放置在浏览器JavaScript、Liquid模板、移动应用或公共代码仓库中。

1. Identify the conversion boundary

1. 确定转化触发节点

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
.
选择每个已完成订单仅执行一次的后端节点：
  • Shopify：订单状态Webhook、服务器应用或Shopify Function/后端工作流
  • 通用结账系统：服务器端成功处理程序或支付Webhook
  • SaaS应用：支付成功后调用的后端路由
  • Agent或MCP界面：知晓所选追踪码的服务器进程
所有场景的实现方式一致：在服务器端收集订单数据，然后调用
POST /merchant/conversions
接口。

2. Capture the tracking code

2. 获取追踪码

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.
Syndicate Links转化上报需要的是
trackingCode
，而非
publisherCode
。
常见来源：
  • POST /affiliate/links
    接口返回的追踪链接码
  • 买家通过Syndicate Links点击URL进入时存储的代码
  • 经批准的Agent发布流程提供的代码
将追踪码与购物车、结账会话、客户会话或订单元数据一起持久化存储，以便后端在支付完成后能够访问该代码。

3. Fire the conversion

3. 触发转化上报

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.
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
若系统具备相关数据，还可支持
clickId
和
items
等可选字段。确保
orderId
稳定且唯一。
成功响应状态为
201 Created
，包含转化事件、佣金信息、归因元数据以及追踪费用详情。

4. Verify recent conversions

4. 验证近期转化记录

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
bash
curl -sS "https://api.syndicatelinks.co/merchant/conversions?limit=5" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
需检查以下内容：
  • 预期的
    orderId
  • saleAmount
    与订单总额匹配
  • status
    为
    pending
    或
    confirmed
  • affiliateId
    已填充
  • attributionMethod
    已设置，通常为
    tracking_code
    ，除非通过点击匹配升级

Platform notes

平台注意事项

Shopify

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.
请勿将商家API密钥粘贴到主题Liquid中。请使用经过认证的后端应用、订单Webhook或服务器函数。若在结账前获取到追踪码，可将其存储在订单元数据中。

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.
从支付成功Webhook或服务器成功路由调用转化接口，请勿从浏览器感谢页面调用。

SaaS apps

SaaS应用

Call the conversion endpoint from your backend payment handler, for example a Stripe, Paddle, Chargebee, or Lemon Squeezy webhook worker.
从后端支付处理程序调用转化接口，例如Stripe、Paddle、Chargebee或Lemon Squeezy的Webhook工作流。

Agent surfaces

Agent界面

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.
若AI Agent可选择或推荐商家链接，请让其将所选追踪码传递给商家服务器。仍需由商家服务器执行经过认证的转化上报操作。

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.
  1. 错误的接口地址：请使用
    https://api.syndicatelinks.co/merchant/conversions
    ，不要添加版本前缀。
  2. 错误的金额字段：API期望的是
    saleAmount
    ，而非
    amount
    。
  3. 错误的归因字段：API期望的是
    trackingCode
    ，而非
    publisherCode
    。
  4. 客户端存储密钥：商家API密钥必须仅在服务器端使用。
  5. 重复的订单ID：重复使用
    orderId
    可能导致上报和对账偏差。

Links

相关链接