Read and approve affiliate commissions

The affiliates capability attributes referred orders to an affiliate, calculates a commission, and — when a commission is approved — posts a balanced entry to accounting. This guide covers what a merchant can do from the portal API: read your affiliates and their commissions, read program stats, and approve a commission.

Most of the money logic runs automatically off the order lifecycle. When a referred order is placed (commerce.order.placed.v1, carrying the shopper’s referral_code), attribution and a pending commission are created for you. When an order is refunded (commerce.order.refunded.v1), its commissions are reversed. You do not call an API for either.

How a commission is calculated

A commission amount is always floor(gross_order_cents * commission_rate_bps / 10000). The base is the gross order amount — a documented business rule. Commissions are append-only: a commission’s status only ever moves pending -> approved, or pending/approved -> reversed. A refund tombstones the order, and a database trigger makes it impossible to mint a new commission against a refunded order, so a late redelivery of an order event can never resurrect money.

Approving a commission posts a balanced transaction to accounting with a deterministic idempotency key derived from the commission id, so approving (or replaying an approval of) the same commission twice posts exactly once.

What a merchant credential can do

Merchant affiliate routes are mounted under /v1/merchant. Reads require the read:own_affiliates scope; the approve route requires manage:own_affiliates — the same read/act split as orders, so a read-only key can never move money.

⚠️

Creating affiliates, setting commission rates, and configuring multi-level tiers are operator-side actions today, not merchant API calls. As a merchant you read your program and approve commissions; provisioning an affiliate is done by the platform operator.

Read and approve

List your affiliates

curl https://api.ruo.pro/v1/merchant/affiliates \
  -H "Authorization: Bearer fdk_your_key_here"

Each affiliate carries id, user_ref, referral_code, commission_rate_bps, status, parent_affiliate_id, and created_at. A failed read returns a 503 — never a fabricated empty list.

Read one affiliate with its commissions

curl https://api.ruo.pro/v1/merchant/affiliates/{id} \
  -H "Authorization: Bearer fdk_your_key_here"

This returns the affiliate plus its commissions. A commission row includes amount_cents, commission_rate_bps, order_ref, commission_level (0 for a direct commission, higher for multi-level upline), source (order or post_consultation), currency, status, and reversed_at / reversal_reason when reversed. An affiliate in another tenant reads back as a 404, never a cross-tenant leak.

Read program stats

curl https://api.ruo.pro/v1/merchant/program-stats \
  -H "Authorization: Bearer fdk_your_key_here"

Approve a commission

This requires manage:own_affiliates. It transitions a pending commission to approved and posts the balanced accounting entry. It is idempotent: a repeat call replays the same posting rather than doubling it.

curl -X POST https://api.ruo.pro/v1/merchant/affiliates/commissions/{commissionId}/approve \
  -H "Authorization: Bearer fdk_your_key_here"

A response carries the updated commission, the accounting_transaction_id, and accounting_replayed. Approving an already-reversed commission is refused (409 already_reversed); an unknown or cross-tenant commission is a 404.

React to commission events

If you run webhooks, subscribe to the affiliate events rather than polling. Both are published as commissions move:

affiliate.commission.posted.v1 — a new direct or multi-level commission.
affiliate.commission.reversed.v1 — a commission reversed by a refund.

Each payload is self-contained (commission id, affiliate id, order ref, amount cents, and timing), so a consumer never has to call back to use it.

What is automatic vs. what you configure

Automatic: attribution on a referred order, commission calculation, multi-level upline commissions, refund reversal, and the accounting posting on approval.
You do: read your program and decide when to approve pending commissions.
Operator-side: creating affiliates, rates, and multi-level configuration.

API reference — the full module and route index.
Webhooks — subscribing to affiliate.commission.* events.

Marketing campaigns Fraud controls