What you earn

Every account earns a share of the price of every order it fulfils. It accrues as the order is fulfilled — there is nothing to claim, invoice or reconcile at the end of a month.

The rate is your volumeCopy Anchor Link

Volume is fulfilled purchases over the last 30 days, and the tier follows it. Nobody at Tizon sets your rate. commission_bps carries it in basis points, so 1500 is 15%.

A negotiated: true flag means an agreed rate is overriding the ladder, so commission_bps is not what tier would pay. That is rare; almost every account is on the ladder.

Reading the Revenue CentreCopy Anchor Link

curl https://api.tizon.mobile/v1/revenue \
  -H "Authorization: Bearer $TIZON_KEY"

{
  "object": "revenue",
  "tier": "growth",
  "commission_bps": 1750,
  "negotiated": false,
  "volume": { "amount": 1240000, "currency": "USD" },
  "next_tier": {
    "tier": "scale",
    "from": { "amount": 5000000, "currency": "USD" },
    "commission_bps": 2000
  },
  "balance": { "amount": 21700, "currency": "USD" },
  "lifetime_earned": { "amount": 184300, "currency": "USD" },
  "taken_as_credit": { "amount": 162600, "currency": "USD" },
  "paid_out": { "amount": 0, "currency": "USD" },
  "payable": { "amount": 21700, "currency": "USD" },
  "payout_address": null
}

Two balances matter and they are not the same number:

• balance is what has been earned and not yet moved or paid out — what Tizon owes right now.
• payable is what could leave the system right now: balance less any overdraft the wallet has drawn, never below zero. Tizon does not pay out money the account owes back.

So an account carrying an overdraft can have a healthy balance and a payable of zero. That is deliberate, not a bug.

An account that has bought nothing has a Revenue Centre with nothing in it, not a missing one.

Spending it: creditCopy Anchor Link

Moving earnings into the wallet turns them into credit that buys eSIMs like any other balance:

curl https://api.tizon.mobile/v1/revenue/transfers \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

An empty body moves everything earned. Pass amount to move part of it; more than has been earned is 402 amount_above_balance, and an empty Revenue Centre is 402 nothing_to_transfer.

Taking it out: LightningCopy Anchor Link

Payouts go to a Lightning address (LUD-16) — name@domain, the same shape as an email. Set it once:

curl -X PUT https://api.tizon.mobile/v1/revenue/payout_address \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lightning_address": "earnings@getalby.com" }'

It is checked for shape and for pointing somewhere public. Whether anything actually answers there is found out by the first payout. Setting it moves no money, so it needs no Idempotency-Key.

Then ask for a payout:

curl https://api.tizon.mobile/v1/revenue/payouts \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

An empty body pays out everything payable. The amount is taken from the balance at once and sent in the background, so it comes back pending:

{
  "id": "pyo_01J9Z8Y4T7W2Z5B8E3H6K9N2Q5",
  "object": "payout",
  "status": "pending",
  "amount": { "amount": 21700, "currency": "USD" },
  "lightning_address": "earnings@getalby.com",
  "payment_hash": null,
  "amount_sats": null,
  "failure_reason": null
}

It is denominated in USD and sent as satoshis worth that amount at the moment the invoice is made. The routing fee is Tizon's — the address receives the whole amount.

A payout ends succeeded or failed, and a failure returns the money to the Revenue Centre. Listen for payout.succeeded and payout.failed rather than polling.

Worth handling by name:

A payout already asked for keeps the address it was asked with, so changing the address never redirects one in flight.

Where every number came fromCopy Anchor Link

curl -G https://api.tizon.mobile/v1/revenue/entries \
  -H "Authorization: Bearer $TIZON_KEY" \
  -d limit=20

One entry per accrual, move, payout, or failed payout coming back — kind is earned, taken_as_credit, paid_out or payout_returned, and amount is always positive, with kind carrying the direction.

An earned entry names the order_id that earned it and the rate_bps in force at the time, so a past number explains itself even after your tier has moved.

Trying it on a test keyCopy Anchor Link

Sandbox purchases accrue commission exactly as live ones do, so buy a few things with a test key and watch the Revenue Centre fill. See test mode for funding a test wallet without real money.