Billing›Affiliate attribution

Affiliate attribution.

Affiliate attribution ties a checkout to a referrer code so a commission can accrue when the sale confirms. Attribution is always carried by the affiliateCode field on CheckoutCreate — you set it when you create the checkout. Where the code comes from is up to you: most commonly an ?aff=CODE param on your own store URL that the partner shares and your site forwards.

Disabled by default. The affiliate program is inert until a merchant turns it on. With the program off, an affiliateCode or ?aff= tag is recorded as attribution but no commission is computed and no commission event fires. Enable it from your workspace before relying on the ledger or webhooks below.

Referral links (your store)

Give partners a link to your own store or landing page with an ?aff=CODE param. Your site reads that param — persist it in a cookie or session — and forwards it as affiliateCode when it creates the checkout. That call is what records the attribution. OpenSettle's own hosted /pay/<token> links do not capture ?aff= on their own; the code has to reach the affiliateCode field one way or another.

bash

https://yourstore.com/pricing?aff=PARTNER42

Server-created checkouts

When you create the checkout yourself — so the buyer never hits a link carrying the tag — set the code explicitly with affiliateCode on CheckoutCreate. Use this when your own backend already knows which partner drove the sale.

checkout.ts

const checkout = await os.checkouts.create({
  mode: "payment",
  amount: 4999,
  currency: "USD",
  chain: "base",
  token: "USDC",
  affiliateCode: "PARTNER42", // attribute this sale to the partner
});

When commission accrues

A commission accrues when an attributed sale confirms on chain — not when the checkout is created and not while the payment is still pending. The accrual is written to a commission ledger against the affiliate. Adjustments (for example, when the underlying payment is later refunded) and payouts are tracked as their own ledger entries.

Webhooks

With the program enabled, the commission lifecycle emits these events. They do not fire while the program is off.

commission.accrued — an attributed sale confirmed; a commission was written to the ledger.
commission.adjusted — a previously accrued commission was revised (e.g. the sale was refunded).
commission.paid — a commission was marked paid out to the affiliate.
commission.voided — an accrued commission was cancelled and removed from what is owed.

Not yet wired

Attribution and the commission ledger above are live behind the per-merchant toggle. The referral reward side — granting a credit or reward to the referred customer — and applying a referral at onboarding are not yet built (phase 2). Don't build a flow that promises the referred buyer a reward today; only the affiliate-side accrual exists.

Coupons API reference