# Credits and billing (https://orgasm.dev/docs/credits)

Live sessions draw on your company's prepaid **credits**. You pay for what orgasm.dev counts in a session, never for time on camera:

| Charged for | Credits | Counted when |
| --- | --- | --- |
| [An orgasm](#orgasms) | 1 | its first call arrives: an onset, a peak, or while the subject is undetermined, either |
| [A ruin](#ruins) | 1 | in place of an orgasm, when your product stopped stimulation at the point of no return just before it began |
| [An edge](#edges) | ½ | imminence reached 0.6 and fell back below 0.3 with no orgasm called in between |
| [The session minimum](#the-session-minimum) | ½ | a session with more than a minute of media ends having counted none of the above |

Credits belong to your company, shared by its [team](/docs/guides/teams). Every company starts with **20 free credits**. Test keys are free and unlimited. What credits cost, and how to buy them, is on [Pricing](/pricing).

## Orgasms [#orgasms]

An orgasm is charged once, by its `orgasmIndex`, when its first call arrives. A woman's onset and end, a man's peak and the end read from his face, and every call made while the subject is undetermined share one index and one charge. Two orgasms in a session are two credits.

## Ruins [#ruins]

A ruin is an orgasm that begins after your product has stopped stimulation at the point of no return. orgasm.dev tells it from an orgasm by your own [stimulation reports](/docs/api/live-sessions/reportStimulation): an orgasm is a ruin when the last report before it began was `off`, sent within the 30 seconds before while `p30` was at 0.75 or above, the [ruin preset's](/docs/concepts/presets#ruin) stop level. Its `orgasm.end` carries `ruined: true`.

A ruin costs what an orgasm costs, so reporting a stop changes what you count, never what you pay. Report the stop as it happens: a report sent after the orgasm's first call does not change how it was counted.

```json
{
  "id": "evt_20wbdv4aq0o16ns5dfu9",
  "object": "event",
  "type": "orgasm.end",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1172,
  "streamTimeS": 643.9,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 640,
    "startedAtS": 612,
    "durationS": 28,
    "calledAtS": 643.9,
    "lagS": 3.9,
    "detector": "face_end",
    "score": null,
    "threshold": null,
    "ruined": true
  },
  "wallTime": "2026-10-16T14:01:05.390Z"
}
```

## Edges [#edges]

An edge is an approach that receded: `p30` reached 0.6, the [edge preset's](/docs/concepts/presets#edge) back-off level, and fell back below 0.3, its resume level, with no orgasm called in between. orgasm.dev counts it on its side and sends `edge.completed` with the reading that completed it, on the stream, the socket and to your webhooks. Its `confidence` is the lowest of the approach's readings.

```json
{
  "id": "evt_2gi9on772qb0beswjxgp",
  "object": "event",
  "type": "edge.completed",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 706,
  "streamTimeS": 411,
  "confidence": "high",
  "data": {
    "edgeIndex": 1,
    "startedAtS": 362,
    "eventAtS": 411,
    "durationS": 49,
    "peakP30": 0.687
  },
  "wallTime": "2026-10-16T14:00:42.100Z"
}
```

An orgasm called during an approach makes it an orgasm, not an edge, and so does the fall of imminence after it: a new approach starts only once `p30` is back below 0.3. Without the microphone no orgasm can be called, so in a face-only session every approach that recedes is an edge.

## The session minimum [#the-session-minimum]

A live session with more than a minute of media that ends having counted no orgasm, ruin or edge is charged half a credit, so an empty session is never free. A session that never received media is not charged, and neither is one that ended because orgasm.dev lost its analysis capacity (`interrupted`) or failed (`error`).

## Where charges show up [#where-charges-show-up]

- **On the session.** Every live session has `charges`: `orgasms`, `ruins`, `edges`, `sessionMinimum` and the `credits` it drew so far.
- **In the events.** `edge.completed` and `orgasm.end`'s `ruined` say what was counted, as it happens.
- **In usage.** [`getUsage`](/docs/api/account/getUsage) counts `orgasms`, `ruins`, `edges`, `sessionMinimums` and `credits` per day.
- **In the balance.** [`getCredits`](/docs/api/account/getCredits) returns what your company has left, the free credits remaining, and each package with its price per credit and expiry. Your console's Billing tab shows the same, with the last 30 days by unit.
- **By charge, in dollars.** [`listCharges`](/docs/api/account/listCharges) lists each charge with what it cost and the references of the session it belongs to ([cost attribution](#cost-attribution)). Admins and Billing members see the same in the Billing tab.

Charges are made once each: a redelivered event, a reconnect or a retry never charges twice.

## Credits, in order [#credits-in-order]

Free credits are used first, then whichever package expires soonest. A package's credits last 12 months from the day they post; the free 20 do not expire. A charge that a package cannot cover takes the rest from the next one.

## At zero [#at-zero]

A new live session is refused with [`credits_exhausted`](/docs/guides/errors#credits_exhausted) (`402`). Sessions already running finish, and what they use past zero comes out of the next package that posts, so the balance can read below zero until then. Test keys keep reaching the sandbox.

You hear before then. When your balance falls to 20% of your latest package (4 of the free 20), orgasm.dev sends `credits.low` to the live endpoints that subscribed to it, once per package:

```json
{
  "id": "evt_5c2x8v1b4n7m0q3w6e9r",
  "object": "event",
  "type": "credits.low",
  "mode": "live",
  "wallTime": "2026-10-16T14:21:07Z",
  "data": { "domain": "studio.example", "balance": 4, "threshold": 4, "freeRemaining": 4, "packageId": "free" }
}
```

It belongs to your company rather than a session, so it has no `sessionId`, `sequence` or stream time. Subscribe to it like any other [webhook](/docs/guides/webhooks).

## Cost attribution [#cost-attribution]

To see what each of your users and sessions cost, say who a session is for when you create it:

- **`userReference`**: your own pseudonymous id for the person, the same on each of their sessions. Never their email, phone or name: derive it from your user id with a key only you hold, as below.
- **`clientReferenceId`**: your id for the session, such as a booking, an order or a round.
- **`metadata`**: up to 20 string values of your own, like a plan, a product, a region or a campaign. Each key is a dimension your costs break down by. Keep personal data out of it.

Both references are 1 to 128 letters, digits, `.`, `_`, `:` or `-`, with at least one letter. A value with `@`, `+` or a space, or one made only of digits, is refused with `422 invalid_request`, so an email address or a phone number never gets in by mistake.

```ts title="server.ts"
import { createHmac } from 'node:crypto';

// The same person, the same reference; nobody without REFERENCE_KEY can link it back to them.
const userReference = `u_${createHmac('sha256', process.env.REFERENCE_KEY!).update(user.id).digest('hex').slice(0, 32)}`;

await fetch('https://orgasm.dev/v1/live-sessions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ consent, capabilityHash, userReference, clientReferenceId: `booking_${booking.id}`, metadata: { plan: user.plan } }),
});
```

Each charge is valued at the price per credit of the package it drew on. A charge on the free credits costs $0. A charge used [past zero](#at-zero) has no price until the next package posts and covers it, at that package's price. In the Billing tab, Admins and Billing members pick a month and break its costs down by day, unit, API key, user reference, session or any metadata key, and open a session to see its charges. [`listCharges`](/docs/api/account/listCharges) gives your systems the charges, filtered by `userReference`, `clientReferenceId`, `sessionId` or dates, with a secret key or a read-only [billing key](/docs/guides/teams#billing-keys).

References and metadata are kept for 13 months, then erased; the charges stay, without them. To delete one person's data, purge their sessions by reference ([retention and deletion](/docs/concepts/compliance#retention-and-deletion)).

## Reconciling with your invoices [#reconciling-with-your-invoices]

- **The statement.** For each month, the Billing tab's Statement shows your prepaid credits in dollars: at the start of the month, packages posted, used by sessions, returned by reviews, expired unused, and at the end. The month's charges add up to "used by sessions" to the cent.
- **Two CSV exports** for any month, in UTC:
  - *Charges*: one row per charge, with `id`, `at`, `session_id`, `unit`, `index`, `credits`, `free_credits`, `paid_credits`, `pending_credits`, `amount_usd`, `packages`, `returned`, `own_gpu`, `api_key_id`, `api_key_name`, `user_reference`, `client_reference_id` and `metadata`.
  - *Sessions*: one row per session, with its times, `ended_reason`, `media_seconds`, the key, its references and metadata, what it counted, and `credits`, `pending_credits` and `amount_usd`.
- **Pending.** Credits used past zero are valued when the package that covers them posts, and counted as used in that month.
- **Expired credits** are no session's cost. They appear on their own line, "Expired unused", never spread over sessions.
- **Returns.** A charge returned after a [review](#contesting-a-charge) is marked `returned` and costs nothing. The month of the review shows the return.

Amounts are in dollars to a tenth of a cent (`amount_usd` has three decimals), because a half-credit charge at some prices ends in half a cent.

## Testing in the sandbox [#testing-in-the-sandbox]

Sandbox sessions count everything a live session would, and draw nothing: their `charges` show what was counted, with `credits` at 0. The `edge` scenario counts three edges, `ruin` a ruin (it reports stimulation on at the baseline and off where the ruin preset stops, as your product would), `finish` two orgasms, and `face-only` an edge. A session you end after more than a minute of a scenario's media, before anything is counted, shows the minimum.

```bash
curl -s https://orgasm.dev/v1/live-sessions \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{"consent":{"subjectIsAdult":true,"subjectConsented":true,"ageVerification":"document"},"sandbox":{"scenario":"edge","speed":60}}'
```

## Contesting a charge [#contesting-a-charge]

Detectors make false calls. If a charge was wrong, write to [support@orgasm.dev](mailto:support@orgasm.dev) within 14 days with the session and the call. If the review agrees, the credit is returned to the package it came from.

## Your own GPUs [#your-own-gpus]

Sessions on [your own GPUs](/docs/guides/own-gpus) are counted the same way and marked as yours; their price is set in your statement of work.
