Report a sale. We handle the rest.

OVERVIEW

What this API is for

A brand runs an affiliate program on Trendly. Creators join, the brand approves them, and each approved creator gets a personal discount code. When a customer uses that code in your store, the creator earns commission. Trendly pays them on a schedule the brand sets.

We need one thing from you: the orders. Everything after that is ours.

Two rules apply everywhere in this API.

Already have an orders API? We can poll it instead. Ask your Trendly contact for the integration specification. Most merchants find pushing to us takes a day against a week, so this is the path we recommend.

QUICKSTART

From nothing to a working call

1. Get a key. Ask your Trendly contact. If you have a Trendly login, go to Developers and create one yourself. Start with a test key. It looks like trk_test_….

2. Check it works. This returns the program your key belongs to and the three settings that determine what a creator takes home.

curl https://api.trendly.com.sa/v1/ping \
  -H "Authorization: Bearer trk_test_YOUR_KEY"

{
  "ok": true,
  "environment": "test",
  "key_name": "Calo checkout",
  "scopes": ["codes:read", "orders:read", "orders:write", "program:read"],
  "program": {
    "id": "3b0c8f14-0a2e-4c77-9b31-6f5f2a1d4e88",
    "name": "Calo Market Partners",
    "currency": "SAR",
    "status": "active",
    "commission_basis": "net_ex_vat_ex_shipping",
    "hold_period_days": 14,
    "payout_cycle_days": 30
  },
  "server_time": "2026-09-18T09:14:22Z"
}

3. Report an order. This is the whole integration.

curl -X POST https://api.trendly.com.sa/v1/orders \
  -H "Authorization: Bearer trk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_1001",
    "discount_code": "SARA10",
    "status": "confirmed",
    "currency": "SAR",
    "subtotal_amount": "240.00",
    "discount_amount": "24.00",
    "shipping_amount": "15.00",
    "tax_amount": "34.65",
    "total_amount": "265.65",
    "placed_at": "2026-09-08T11:42:03+03:00"
  }'

A test key records the order in Trendly and flags it as test. Open the brand's dashboard and you will see it there, excluded from their figures and from payouts.

{
  "mode": "test",
  "recorded": true,
  "created": true,
  "order_id": "ord_1001",
  "status": "confirmed",

  "attribution": {
    "attributed": true,
    "code": "SARA10",
    "creator_name": "Sara A.",
    "membership_id": "9c1e77a2-4b3d-4e91-8f22-11c0a7d5b6e3"
  },

  "commission": {
    "basis_amount": "216.00",           // 240.00 goods − 24.00 discount
    "basis": "net_ex_vat_ex_shipping",  // VAT and shipping excluded, per the program
    "rate_type": "percentage",
    "rate_value": "10.00",
    "rate_source": "program_default",   // which link in the rate chain won
    "amount": "21.60",
    "currency": "SAR",
    "capped": false,
    "payable_after": "2026-09-22T11:42:03Z"
  },

  "warnings": [
    "Recorded as a test order. It appears in Trendly marked as test, and is excluded
     from the program's figures and from every payout."
  ]
}

Swap trk_test_ for trk_live_ and the same request counts for real. That is the only difference between the two environments.

AUTHENTICATION

Keys

Send your key as a bearer token on every request. If your gateway strips the Authorization header, send the same value as X-API-Key instead.

Authorization: Bearer trk_live_7Qa4xN2pLmK8vR3sT1wY6z

Scopes

A key carries some or all of four scopes. Use codes:read on its own for anything running in a checkout. A checkout is the most exposed place a key lives, and one that can only answer "is this code valid?" is worth little to whoever takes it.

ORDERS

Reporting an order

Call this when an order is placed, and again whenever it changes: confirmed, cancelled, refunded, partially refunded, flagged. Same call, same order_id. We match on it and reconcile.

Fields

Warnings

A successful response may include a warnings array. The order was accepted, so never retry on a warning. Each one is worth fixing though. We warn when amounts do not balance to subtotal − discount + shipping + tax = total, when a timestamp has no UTC offset, when a currency had to be assumed, and when a refunded order arrives without a refunded amount.

STATUSES

Order statuses

Map your own statuses onto these six and send your Trendly contact the mapping.confirmed matters most. It starts the clock on a creator's earnings.

REFUNDS

Refunds and cancellations

Send the same order_id with the new status. Commission is held through the program's refund window before it becomes payable, so most refunds are absorbed before any money moves.

# Same order_id. We reverse the proportional share of the commission.
# If it was already paid out, a clawback carries into the next cycle.

curl -X POST https://api.trendly.com.sa/v1/orders \
  -H "Authorization: Bearer trk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_1001",
    "status": "partially_refunded",
    "currency": "SAR",
    "subtotal_amount": "240.00",
    "discount_amount": "24.00",
    "shipping_amount": "15.00",
    "tax_amount": "34.65",
    "total_amount": "265.65",
    "refunded_amount": "120.00",
    "placed_at": "2026-09-08T11:42:03+03:00",
    "updated_at": "2026-09-14T10:02:00+03:00"
  }'

If a refund arrives after a payout has gone out, we do not rewrite history. The original accrual stands and a reversal is appended, which carries into the creator's next cycle as a clawback. This is what lets a statement from three months ago still reconcile.

BATCH

Batches and backfill

Up to 500 orders per call, for backfills and nightly reconciliation. Results are per order. One malformed row does not reject the other 499, and the response names the row to fix.

# For backfills and nightly reconciliation. Up to 500 per call.
# Results are per order, so one malformed row does not reject the other 499.

curl -X POST https://api.trendly.com.sa/v1/orders/batch \
  -H "Authorization: Bearer trk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orders": [ { "order_id": "ord_1", ... }, { "order_id": "ord_2", ... } ] }'

The response is always 200, because the batch itself succeeded. Each entry carries its own status. Rejected entries carry the same error.code and error.hint a single call would have returned.

CODES

Discount codes

Trendly issues each approved creator a personal discount code. Poll this endpoint to mirror them into your own discount engine, with updated_since set to your last successful run.

# Mirror Trendly's codes into your own discount engine.
# Use updated_since, not created_since. A code disabled this morning must come
# back even though it was created months ago.

curl "https://api.trendly.com.sa/v1/codes?updated_since=2026-09-01T00:00:00%2B03:00&limit=200" \
  -H "Authorization: Bearer trk_live_YOUR_KEY"

Pagination is by cursor. Pass back next_cursor unmodified; it is opaque and stable, so codes being approved while you page cannot make you skip or repeat one.

Two kinds of code

CODES

Who issues the code

A creator is approved in Trendly and needs a discount code. There are four ways that code comes to exist, and the right one depends on whether you already run a coupon engine and whether it can be called from outside. You can mix them: the model is chosen per program, and a single creator can be moved from one to another without losing their history.

Sending us a code

Use this when your engine owns the code. It works for the first code a creator gets and for every change after it, so a rotation is the same call as a creation. Requires a key carrying codes:write.

curl -X PUT https://api.trendly.com.sa/v1/affiliates/aff_8f31c2/code \
  -H "Authorization: Bearer trk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9d1c4f6a-3b77-4a21-9c5e-0f2b8d6a1e44" \
  -d '{
    "code": "SARA15",
    "external_code_id": "cpn_81f3",
    "reason": "Issued by the coupon engine after manual verification"
  }'

The affiliate_id is ours. You already hold it: it is on every order we send you and on every row of GET /v1/codes. Your own identifier belongs in external_code_id, which we store and hand back, so neither side has to keep a mapping table.

Us asking your engine

The mirror image, for engines that can be called from outside. You give us a URL and a shared secret; we call it once when a creator is approved and use the code you return. This is the only endpoint in these docs that you host.

// You host this. We call it once, when a creator is approved in Trendly.
app.post("/trendly/coupons", async (req, res) => {
  const { affiliate_id, creator, suggested_code, discount } = req.body;

  // Your engine owns the final code. Take our suggestion or ignore it.
  const coupon = await coupons.create({
    code: suggested_code,
    percent_off: discount.value,
    metadata: { trendly_affiliate_id: affiliate_id, handle: creator.handle },
  });

  // Reply inside 10 seconds. Anything slower is treated as a failure and retried.
  res.json({ code: coupon.code, external_code_id: coupon.id });
});

We wait ten seconds, then retry with backoff for an hour. If it never answers, the creator stays approved and their code is marked failed with your error text against it, visible to the brand, who can retry or type a code in by hand. We do not invent a code to fill the gap, because a code your engine has never heard of sells nothing and the failure would surface as missing revenue weeks later.

Every code is kept

Codes are never edited in place. Replacing one closes the old record and opens a new one, so a creator carries a history rather than a current value: what the code was, who changed it, when, and why. Orders stay attached to the code that actually brought them in, which means last quarter's numbers do not move when somebody rotates a code today.

GET /v1/codes returns superseded codes as well as live ones. Filter on status if you only want the current set, and read replaced_by to follow a chain. The brand sees the same history in the dashboard, next to the creator it belongs to.

CHECKOUT

Validating a code at checkout

If your checkout does not hold its own copy of our codes, ask us in real time. Send the code and, optionally, the cart total; we say whether it is usable and what to take off.

curl -X POST https://api.trendly.com.sa/v1/codes/validate \
  -H "Authorization: Bearer trk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "SARA10", "cart_total": "240.00" }'

Each rejection has its own reason: unknown_code, disabled, expired, not_yet_valid, below_minimum, not_provisioned. A shopper who mistyped one character and one whose code genuinely ran out should not be sent down the same path.

Use our discount_amount rather than calculating your own. We round half-up to the halala. Rounding the other way puts you a riyal out on every order of a certain shape, which shows up later as a reconciliation gap nobody can explain.

ERRORS

When something is wrong

Every failure has the same shape, including authentication failures.

{
  "error": {
    "code": "invalid_amount",
    "message": "'total_amount' is not a decimal amount: SAR 240",
    "field": "total_amount",
    "hint": "Send money as a decimal string. Use \"240.00\", not 240.0 and not \"SAR 240\". JSON numbers are doubles and lose halalas at volume.",
    "documentation_url": "https://www.trendly.com.sa/developers#orders"
  },
  "request_id": "8f14d2a1-7c3b-4e55-9a20-3d6b1f0c9e47"
}

Branch on error.code. It is stable. error.message and error.hint are written for whoever reads your logs, and error.field names the part of your payload that is wrong.

Idempotency

Optional. Send Idempotency-Key on a write and a replay returns the original response rather than a fresh one. Writes are already idempotent on order_id, so this is for your retry logic rather than the ledger. Without it a retry still cannot double-pay, it just reports created: false the second time.

TESTING

Testing, and what go-live looks like

A test key runs the same engine as a live one. Same parser, same code lookup, same commission basis, same rate chain. No fixture data and no mock. A clean 200 from a test key proves your payload works, not that a sandbox was willing to accept it.

Test orders are recorded and appear in Trendly flagged as test. Send one, then open the brand's dashboard and look at it. They are excluded from the program's figures and from every payout, and a brand can clear them from Developers whenever they want a clean slate.

Your own call history for the last 30 days, with request and response bodies. This is the same log the brand sees in Trendly, reachable with your key. You do not need a Trendly account to debug your own integration.

curl "https://api.trendly.com.sa/v1/events?failures_only=true&limit=10" \
  -H "Authorization: Bearer trk_test_YOUR_KEY"

Before you switch to a live key

PRIVACY

What we do and do not want

We do not want customer personal data. No names, emails, phone numbers or addresses, in any field, ever. We reject a customer_ref that looks like an email or a phone number rather than storing it.

customer_ref must be pseudonymous: a hash or an internal key, stable per customer and meaningless outside your system. We use it for the new vs returning split and to detect a creator buying through their own code. Omit it if you prefer. You lose those two features and nothing else.

Order data reaches the brand that owns the program. The creator whose code was used sees their own orders only: date, status, order value, and their commission. Never another creator's orders, and never anything about the customer. Keys are stored hashed, excluded from logs, and scoped to one program.

REFERENCE

Everything, in one place