Use the partner tracking API

When a customer places an order using an affiliate coupon code, call the tracking API from your server to record the sale, calculate the commission, and update the partner's balance. The API handles duplicate prevention and customer attribution automatically.

Authentication

All requests require your API key in the Y-API-Key header. You can find your API key in the dashboard under Settings → API.

Endpoint

POST https://yaplet.com/api/affiliates/track/{affiliate_code}

Replace {affiliate_code} with the partner's coupon code — the code your customer entered at checkout. If the code doesn't exist or the partner is not approved, the API returns success: false with a 200 status. That's not an HTTP error — it means no commission was recorded.

Request body

{
  "order_id": "order_12345",
  "total_amount": 100.00,
  "customer": {
    "email": "[email protected]",
    "name": "Jane Smith",
    "customer_id": "cust_789",
    "customer_metadata": { "source": "website" }
  },
  "commission": 10.00,
  "notes": "Summer sale order",
  "timestamp": 1640995200000,
  "product": {
    "id": "prod_123",
    "name": "Pro Plan",
    "category": "subscription"
  },
  "metadata": { "utm_source": "newsletter" }
}

Required fields

Field	Type	Description
order_id	string	Unique order identifier. The same order_id can only be tracked once per organization — duplicates return 409.
total_amount	number	Order total in decimal format. Used for percentage commission calculation.
customer.email	string	Customer email address. Required for customer attribution and deduplication.

Optional fields

Field	Type	Description
commission	number	Override the calculated commission with an exact amount. If omitted, Yaplet calculates from the partner's rate.
timestamp	number	Order time in milliseconds. Values with 10 or fewer digits are treated as seconds and multiplied by 1000; 13-digit values are used as-is. Defaults to current server time.
notes	string	Free-text notes stored with the commission record.
customer.name	string	Customer display name. Defaults to the email prefix if omitted.
customer.customer_id	string	Your system's customer ID for cross-referencing.
customer.customer_metadata	object	Any extra customer data (source, segment, etc.).
product	object	Product info (id, name, category). Stored with the commission for reporting.
metadata	object	Any extra order data (UTM params, campaign IDs, etc.).

Code examples

For complete request and response examples in JavaScript, cURL, PHP, and Python, see the developer documentation linked from the dashboard's Settings → API page.

Response

On success:

{
  "success": true,
  "data": {
    "commission_id": "comm_abc123",
    "partner_id": "partner_xyz",
    "customer_id": "customer_456",
    "commission_amount": 10.00,
    "order_id": "order_12345",
    "affiliate_code": "PARTNER_CODE"
  }
}

On invalid or unapproved code:

{ "success": false, "message": "No approved affiliate partner found for coupon code: PARTNER_CODE" }

Error codes

Status	Meaning
200 + success: false	Code not found or partner not approved — no commission recorded.
400	Missing required fields (order_id, total_amount, or customer.email).
401	Missing or invalid Y-API-Key header.
403	Your organization does not have access to the Affiliates feature.
409	Duplicate — this order_id has already been tracked for your organization.
500	Server error.

Best practices

• Call server-side only. Never expose your Y-API-Key in client-side JavaScript.
• Use unique order IDs. The API rejects duplicate order_id values with a 409 — always pass your order's stable identifier.
• Check success in the response. A 200 with success: false means no commission was recorded — you may have the wrong coupon code.
• Pass timestamps for historical orders. If backfilling past orders, include the timestamp field so reporting dates are correct.

What's next

See Set product-level commission overrides to learn how to pass product data and control which rate applies.