> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trackrev.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> List credit grants and balances, and mark a grant delivered.

Credit endpoints power [non-cash reward programmes](/affiliate/credits-and-fulfilment) — read what
partners and referees have earned, and confirm delivery.

## List credit grants

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.trackrev.io/api/v1/credits?external_user_id=USER_123&status=earned" \
    -H "Authorization: Bearer <your key>"
  ```
</RequestExample>

`GET /api/v1/credits` — credit grants and per-kind balances. **Scope:** any valid key.

<ParamField query="partner_id" type="string">
  Filter by partner. Provide this **or** `external_user_id`.
</ParamField>

<ParamField query="external_user_id" type="string">
  Filter by your own user id. Provide this **or** `partner_id`.
</ParamField>

<ParamField query="status" type="string" default="all">
  `earned`, `delivered`, or `all`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum grants (max 500).
</ParamField>

<ResponseField name="grants" type="array">
  Each grant: `id`, `program_id`, `partner_id`, `commission_id`, `credit_kind`, `amount`, `status`,
  `external_user_id`, `referee_external_user_id`, `earned_at`, `delivered_at`, `created_at`.
</ResponseField>

<ResponseField name="balance" type="object">
  Per credit-kind totals: `{ "<credit_kind>": { "earned": N, "delivered": N } }`.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "grants": [
      {
        "id": 4821,
        "program_id": "p1...",
        "partner_id": "pa1...",
        "credit_kind": "ai_credits",
        "amount": 200,
        "status": "earned",
        "external_user_id": "USER_123",
        "earned_at": "2026-07-20T10:00:00.000Z",
        "delivered_at": null
      }
    ],
    "balance": { "ai_credits": { "earned": 200, "delivered": 0 } }
  }
  ```
</ResponseExample>

## Mark a grant delivered

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.trackrev.io/api/v1/credits/4821/mark-delivered" \
    -H "Authorization: Bearer <your secret key>"
  ```
</RequestExample>

`POST /api/v1/credits/{id}/mark-delivered` — flip a grant from `earned` to `delivered` after you've
applied the credit in your product. **Scope:** secret key (`lk_`).

<ParamField path="id" type="integer" required>
  The grant id.
</ParamField>

Returns `{ "ok": true }`, or `{ "ok": true, "already": true }` if the grant was already delivered.
Firing this also emits a `credit.delivered` [webhook](/developers/webhooks).

<Note>
  If you use a [fulfilment connector](/affiliate/credits-and-fulfilment#fulfilment-connectors),
  delivery is handled for you — you only need this endpoint when applying credit yourself (e.g. via
  the Webhook driver or a custom flow).
</Note>