Use the partner tracking API

Yaplet cannot see your checkout, so your shop has to tell it when a sale happens. When a customer orders with an affiliate coupon code, call the tracking endpoint from your own server: Yaplet records the sale, works out the commission, updates the partner's balance and files the buyer under that partner. Repeat orders and duplicate calls are handled for you.

Authentication

Every request carries your organisation's API key in the Y-API-Key header. Create or replace the key at Settings → Organization settings → API. The full key is shown once, when it is created — copy it then, because Yaplet only stores a hash of it afterwards.

Endpoint

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

Put the partner's coupon code — the one your customer typed at checkout — in place of {affiliate_code}. If no approved partner has that code, the response is success: false with a 200 status. That is 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	Your order's identifier. The same one can only be tracked once per organisation — a repeat comes back as 409.
total_amount	number	Order total as a decimal number. Must be a real number greater than zero and no larger than one billion; a string or a negative value is rejected with 400. Used for percentage commissions.
customer.email	string	The buyer's email address. Yaplet matches on it to recognise repeat customers.

Optional fields

Field	Type	Description
commission	number	The exact amount to credit, instead of letting Yaplet calculate it. Must be zero or more and no larger than one billion. Note that sending 0 falls back to the partner's rate rather than paying nothing.
timestamp	number	When the order happened. Values of 10 digits or fewer are read as seconds and multiplied by 1000; longer values are read as milliseconds. Defaults to the time the call arrives.
notes	string	Free text stored on the commission.
customer.name	string	The buyer's display name. Falls back to the part of the email address before the @.
customer.customer_id	string	Your own identifier for this customer, stored as their External ID.
customer.customer_metadata	object	Anything else you want kept about the buyer.
product	object	Product details such as id, name and category. Stored on the commission for reporting; it does not affect the amount.
metadata	object	Anything else you want kept about the order, such as campaign identifiers.

Where the live reference lives

The dashboard carries a copy of this reference that always matches the running code, including a ready-made request body and both response examples: Marketing → Affiliate Management → API.

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"
  }
}

When the code is unknown or the partner is not approved:

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

Error codes

Status	Meaning
200 with success: false	No approved partner has that coupon code — nothing was recorded.
400	A required field is missing, or total_amount / commission is not a valid number.
401	The Y-API-Key header is missing or does not match a key.
403	Your organisation does not hold the Affiliates permission.
409	This order_id has already been tracked for your organisation.
500	Something went wrong on our side.

Best practices

• Call it from your server, never the browser. The Y-API-Key is an organisation-wide key; anyone who reads it out of your page can use it.
• Use your real order identifier. It is what stops the same sale being counted twice.
• Check success, not just the status code. A 200 with success: false means the coupon code did not match an approved partner.
• Send timestamp when backfilling. Otherwise old orders are dated the moment you imported them and your reports go wrong.

What's next

See Set product-level commission overrides for how to send a per-product amount and which rate wins.