Skip to main content
This walkthrough reports a sale and a refund to POST /v1/revenue, reads the per-event results, and sets the reporting currency so they show up in the console. Use it for revenue your modules don’t already send - ticket sales through the ticketing module are recorded at ingest. See Revenue for how totals work. Call this endpoint from your server only. It takes an org_ key, which is a secret; the browser SDK and publishable keys cannot report revenue.

​
1. Issue an organization API key

If your backend already has an org_ key, skip ahead. Otherwise issue one from a partner admin session (see Admin session tokens). The raw_key is returned only in this response.

​
2. Report a sale

Send a batch of up to 100 events. Amounts are positive integers in minor units - 4500 is €45.00 - with an upper-case ISO 4217 currency.
202 Accepted, with one result per event in request order:

​
3. Report a refund

A refund is its own event with a new event_id and a positive amount. A partial refund just uses a smaller amount.

​
4. Read the results

Each event comes back with one of three statuses:
  • accepted - recorded; id is the stored revenue event.
  • duplicate - this event_id was already recorded with the same type, amount and currency. Nothing changed, so a retried request is safe.
  • rejected with reason: "idempotency_conflict" - this event_id was already used with different money. Nothing changed. Fix a wrong amount with a refund under a new id rather than resending.
A body that fails validation - a decimal amount, a lowercase currency, more than 100 events, both member_external_id and user_id - is refused whole with 422 VALIDATION_ERROR, and nothing in it is recorded. Any credential other than an org_ key - an admin session included - is refused with 401 or 403. Each key can make 600 requests a minute; past that the API answers 429. Things to know:
  • Unknown buyers are kept. A member_external_id that isn’t a member yet is stored as-is and linked automatically once a member with that external_id exists.
  • No XP. Revenue reported here never awards XP. To reward a purchase, send an earning event as well.

​
5. Set the reporting currency

In the console, open Setup › Settings and pick the currency you report in (administrators only). Totals only include events in that currency; events in other currencies are kept and shown as not included. There is no conversion between currencies.

​
Where it shows up

With a currency set, the sale and refund above net to €0.00 with one order and one paying member on Operate › Revenue. Revenue also appears on the tenant dashboard, as lifetime spend on member detail and the members list, on the Revenue dashboard card, and in AI analyst answers - for anyone holding the View revenue capability. See Revenue.