Report a sale. Trendly does 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, and Trendly pays it out on the schedule the brand sets.

Trendly needs one thing from you: the orders.

Two rules apply to everything you send.

QUICKSTART

From nothing to a working call

1. 1

   Step 1: Get a test key

   In the dashboard, open Developers, API keys and create a test key. It starts with trk_test_ and is shown once, so copy it somewhere safe. No Trendly login? Your Trendly contact can issue one.

2. 2

   Step 2: Check it works

   GET /v1/ping says which program the key reached and the three settings that decide what a creator takes home.

   cURLNode.jsPython

   cURL

   Copy

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

   Response

   Copy

   {
     "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. 3

   Step 3: Report an order

   This is the whole integration.

   cURLNode.jsPythonPHP

   cURL

   Copy

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

   Response

   Copy

   {
     "mode": "test",
     "recorded": true,
     "created": true,
     "updated": false,
     "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",
       "basis": "net_ex_vat_ex_shipping",
       "rate_type": "percentage",
       "rate_value": "10.00",
       "rate_source": "program_default",
       "amount": "21.60",
       "currency": "SAR",
       "capped": false,
       "payable_after": "2026-09-22T08: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. Send the same request with a trk_live_ key to record it for real."
     ]
   }

   Check the commission block

   basis_amount is what the rate was applied to: 240.00 of goods minus the 24.00 discount, because this program leaves out VAT and shipping. rate_source says which rate won, and payable_after is when the hold period ends. These are the numbers that get disputed at month end, so check them now against an order you can work out by hand.

   A test key stores the order marked as test. Open the program's Orders in the dashboard and you will see it there, left out of every figure and payout.

4. 4

   Step 4: Go live

   Create a live key (trk_live_) and swap it in. The same request now counts for real. That is the only difference between the two environments.

AUTHENTICATION

Keys

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

Authorization: Bearer trk_live_7Qa4xN2pLmK8vR3sT1wY6z
X-API-Key: trk_live_7Qa4xN2pLmK8vR3sT1wY6z

Scopes

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

Response headers

PROGRAMS

Which program a call is about

A key belongs to your Trendly account, and an account can run more than one affiliate program. Every call lands in exactly one program, chosen in this order.

Otherwise the call is refused with 400 program_required, and the hint lists your programs with their ids. An account with no program yet gets 400 no_program.

# In the body, for POST /v1/orders and /v1/orders/batch:
#   { "program_id": "3b0c8f14-0a2e-4c77-9b31-6f5f2a1d4e88", "order_id": "ord_1001", ... }
# Or as a header, on any call:

curl https://api.trendly.com.sa/v1/codes \
  -H "Authorization: Bearer trk_live_YOUR_KEY" \
  -H "X-Trendly-Program: 3b0c8f14-0a2e-4c77-9b31-6f5f2a1d4e88"

# Or on the query string:
curl "https://api.trendly.com.sa/v1/codes?program=3b0c8f14-0a2e-4c77-9b31-6f5f2a1d4e88" \
  -H "Authorization: Bearer trk_live_YOUR_KEY"

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. Trendly matches on it and updates the order it already has.

Fields

Warnings

A successful response may include a warnings array. The order was accepted, so never retry because of a warning, but each one is worth fixing. Trendly warns when amounts do not add up to subtotal − discount + shipping + tax = total, when a timestamp has no UTC offset (Asia/Riyadh is assumed), when the currency was missing, when placed_at was missing, 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 hold period before it can be paid, so most refunds arrive before any money moves.

# Same order_id, new status. Trendly reverses the refunded share of the commission.
# If it was already paid out, the reversal comes off the creator's next payout.

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",
    "status_changed_at": "2026-09-14T10:02:00+03:00"
  }'

If a refund arrives after a payout has gone out, nothing is rewritten. The original commission stands and a reversal is added, which comes off the creator's next payout. That is what keeps a statement from three months ago reconciling.

BATCH

Batches and backfill

Up to 500 orders per call, for backfills and nightly reconciliation. Every order gets its own result, so one malformed row does not reject the rest, and the response names the row to fix. A batch belongs to one program: put program_id at the top level of the body if your key needs one.

# For backfills and nightly reconciliation. Up to 500 orders per call.
# Each order gets its own result, so one bad row does not reject the rest.

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_1002",
        "discount_code": "SARA10",
        "status": "confirmed",
        "currency": "SAR",
        "subtotal_amount": "180.00",
        "discount_amount": "18.00",
        "shipping_amount": "0.00",
        "tax_amount": "24.30",
        "total_amount": "186.30",
        "placed_at": "2026-09-09T19:05:00+03:00"
      },
      {
        "order_id": "ord_1003",
        "discount_code": "NOURA10",
        "status": "pending",
        "currency": "SAR",
        "subtotal_amount": "95.00",
        "total_amount": "SAR 95",
        "placed_at": "2026-09-09T21:40:00+03:00"
      }
    ]
  }'

The response is 200 whenever the batch itself was read, even if some orders were rejected. Each entry carries orderId and an HTTP-style status, then either the result a single call would have returned, attribution and commission included, or errorCode, message and hint. The entry's own keys are camelCase; the keys inside result are snake_case, as in the single-order answer.

{
  "mode": "live",
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "orderId": "ord_1002",
      "status": 200,
      "result": {
        "mode": "live",
        "recorded": true,
        "created": true,
        "updated": false,
        "order_id": "ord_1002",
        "status": "confirmed",
        "attribution": { "attributed": true, "code": "SARA10", "creator_name": "Sara A.", "membership_id": "9c1e77a2-4b3d-4e91-8f22-11c0a7d5b6e3" },
        "commission": { "basis_amount": "95.00", "basis": "net_ex_vat_ex_shipping", "rate_type": "percentage", "rate_value": "10.00", "rate_source": "program_default", "amount": "9.50", "currency": "SAR", "capped": false, "payable_after": "2026-09-23T21:40:00Z" }
      }
    },
    {
      "orderId": "ord_1003",
      "status": 400,
      "errorCode": "invalid_amount",
      "message": "'total_amount' is not a decimal amount: SAR 95",
      "hint": "Send money as a decimal string. Use \"95.00\", not 95.0 and not \"SAR 95\"."
    }
  ]
}

More than 500 orders returns 400 batch_too_large, and an empty list returns 400 empty_batch.

CODES

Discount codes

When the brand approves a creator, Trendly issues their code as pending: the code exists in Trendly, but a customer cannot use it until it exists at your checkout. Your part is three calls, and until you make the last one the creator is told their code is on its way, not the code itself, so nobody shares a code that fails at checkout.

1. 1

   Step 1: List the codes to add

   GET /v1/codes?status=pending returns each code with its discount and creator.

2. 2

   Step 2: Create them in your discount engine

   Use the code text exactly, with its discount_type and discount_value.

3. 3

   Step 3: Confirm each one

   POST /v1/codes/{code}/confirm. The code goes live, any orders that already used it are credited to its creator, and the creator is told it is ready to share. Confirming twice is harmless. A real order reported with a pending code confirms it too.

# 1. The codes Trendly issued to newly approved creators, not yet in your checkout.
curl "https://api.trendly.com.sa/v1/codes?status=pending&limit=200" \
  -H "Authorization: Bearer trk_live_YOUR_KEY"

# 2. Create each one in your discount engine, with its discount_type and discount_value.

# 3. Tell Trendly it exists. The code goes live and its creator is told it is ready.
curl -X POST https://api.trendly.com.sa/v1/codes/SARA10/confirm \
  -H "Authorization: Bearer trk_live_YOUR_KEY"

Needs codes:read, the same key that lists the codes. Answers with the code, now active. A code that is disabled or failed cannot go live and answers 409 code_not_confirmable. If nobody on the brand's side writes code, the dashboard does the same: each program's Creators tab lists the codes to add, with Mark added.

Keeping your engine in step

To mirror every change (new codes, and codes switched off when a creator leaves or a code is replaced), poll GET /v1/codes with updated_since set to the time of your last successful run.

# Mirror Trendly's codes into your own discount engine.
# updated_since, not a creation date: a code disabled this morning comes 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"

limit defaults to 100, up to 200. When has_more is true, pass next_cursor back unchanged as cursor. The cursor is stable, so codes changing while you page cannot make you skip or repeat one.

Kinds

Filter with ?kind=, or leave it out to get all three. Filter by state with ?status=.

Statuses

One code, by its text. Returns 404 not_found if the program has no such code.

CODES

Where codes come from

Every approved creator gets one personal code. It can start in Trendly or in your own coupon engine, and you can mix the two within a program.

Replacing a code

The brand can reissue a creator's code from the dashboard. The old code is disabled, not deleted, and stays in GET /v1/codes with status disabled. Orders keep the code that brought them in, so last month's figures do not move when a code is replaced today. If you mirror codes, switch off the disabled ones.

Removing a creator from the program disables every code they hold the same way: their personal code and any code a campaign gave them. A code's text is unique within a program across every status, disabled included, so it is never issued again, to anyone. A returning creator or a replaced code always gets new text.

CHECKOUT

Validating a code at checkout

If your checkout does not keep its own copy of the codes, ask Trendly in real time. Send the code and, if you have it, the cart total as cart_total. The answer says whether the code can be used and how much 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, not_provisioned, not_yet_valid, expired, below_minimum. A shopper who mistyped one character and one whose code genuinely ran out should not be sent down the same path.

Use the discount_amount in the answer rather than working out your own. It is rounded half up to the halala. Rounding the other way puts you a halala out on some orders, 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://trendly.com.sa/developers/affiliate#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, error.field names the part of your payload that is wrong, and documentation_url links to the section of this page that explains it.

Error codes

Idempotency

Optional. Send an Idempotency-Key header (up to 128 characters) on a write and a retry with the same key and the same body gets the original response back. The same key with a different body returns 409. Writes are already matched on order_id, so this is for your retry logic, not for the ledger: without it a retry still cannot pay twice, it just reports created: false the second time.

TESTING

Testing, and what go-live looks like

A test key runs the same code as a live one: the same parser, code lookup, commission basis and rate chain. There is 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 stored and appear in Trendly marked as test. Send one, then open the program's Orders in the dashboard and look at it. Test orders are left out of the program's figures and every payout, and the 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, for the key's environment. It is the same log the brand sees in Trendly, reachable with your key, so you do not need a Trendly login to debug your integration. Filter with failures_only=true and search; limit defaults to 25. To page back, pass the next_before you got as before.

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

One call in full, by the id from its X-Request-Id header.

Before you switch to a live key

PRIVACY

What Trendly does and does not want

Trendly does not want customer personal data. No names, emails, phone numbers or addresses, in any field. A customer_ref that looks like an email or a phone number is rejected with 400 pii_in_customer_ref, not stored.

customer_ref must be pseudonymous: a hash or an internal key, the same for each customer and meaningless outside your system. It is used for the new and returning split and to spot a creator buying through their own code. Leave it out 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 and kept out of logs.

REFERENCE

Everything, in one place