---
title: "Claim Topup"
method: POST
path: "/v2/billing/claim"
tags: ["billing"]
---

# Claim Topup

`POST /v2/billing/claim`

## Request

- Base URL: `https://api.etymolt.com`
- URL: `https://api.etymolt.com/v2/billing/claim`
- Auth: none declared

Credit a paid Stripe Checkout session to a buyer's API key.

Auth: gated by ETYMOLT_ADMIN_TOKEN. Without it, the endpoint 404s —
minting credits is not a public capability. Operator/founder uses this
via curl with the admin token to rescue a stuck purchase.

Returns 200 with `ok=True` + the new balance on success. Returns 200 +
`ok=False` + a reason on graceful failure (e.g. email not found) so the
caller can decide whether to escalate. Returns 4xx only on hard errors
(bad input, unknown sku).

## Headers

- `X-Admin-Token` string, nullable

## Request body

- ClaimRequest: Body for POST /v2/billing/claim. At least one of (api_key_hash, email) must be provided. `sku` defaults to `topup_10` — the only PAYG SKU as of 2026-05-13.
  - `stripe_session_id` string, required: Stripe Checkout session id (cs_...)
  - `stripe_event_id` string, nullable: Optional Stripe event id for idempotency anchoring. If provided, repeated claims with the same event id are no-ops.
  - `sku` string
  - `api_key_hash` string, nullable: sha256 hex of the buyer's API key. Preferred — direct credit path.
  - `email` string, nullable: Buyer's email. Used to look up the API key when api_key_hash is missing.
  - `amount_usd` number, nullable: Purchase amount for the receipts ledger. Optional.

## Response `200`

Successful Response

- ClaimResponse
  - `ok` boolean, required
  - `verdicts_credited` integer, required
  - `api_key_hash_prefix` string, nullable
  - `new_balance` object, nullable
  - `sku` string, required
  - `stripe_session_id` string, required
  - `note` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/etymolt/apis/etymolt-verify-ai-generated-brand-names.md) · [All operations](https://skmtc.dev/etymolt/apis/etymolt-verify-ai-generated-brand-names/llms.txt) · [OpenAPI document](https://skmtc.dev/etymolt/apis/etymolt-verify-ai-generated-brand-names/revisions/7228ffa1efa7?raw)