---
title: "Credits"
description: "Check your organization's prepaid credit balance and redeem credit codes."
canonical: "https://docs.primitive.dev/docs/credits"
last-updated: "2026-05-17T00:00:00.000Z"
---

# Credits

Prepaid usage credit pays for usage beyond your plan's monthly credit. Credit comes from redeemed credit codes and from credit granted to your organization. Credits are denominated in your account currency (USD).

Amounts on the credits API are in **micros**: `1` USD = `1_000_000` micros, so a balance of `5_000_000` micros is `$5.00`.

## Prerequisites

- An API key. See [Quickstart](/docs/quickstart). Credit requests authenticate with an API key (`Authorization: Bearer prim_...`).

You do not need to look up your organization id: it is resolved from your API key.

## Check the balance

Read the current balance with `GET /v1/credits/balance`.


```
curl https://api.primitive.dev/v1/credits/balance \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"
```


```
{
  "success": true,
  "data": {
    "budget": null,
    "prepaid_credit": {
      "currency": "usd",
      "remaining_micros": "4200000",
      "next_expires_at": null
    }
  }
}
```

FieldMeaning`prepaid_credit.currency`The credit's currency, which is your organization's billing currency (e.g. `usd`).`prepaid_credit.remaining_micros`What the credit can still pay for, in micros. It goes down as usage beyond your plan's monthly credit is paid from it.`prepaid_credit.next_expires_at`The earliest expiry among credits with a balance, or `null` when none of them has an expiry date.`budget`Always `null`. It is kept so existing clients keep working.

`prepaid_credit` is `null` when there is no such credit. It is left out of the response when an exact figure cannot be given right now, for example in the first few minutes after a grant while the new credit is being activated; the rest of the balance is still returned.

## Redeem a credit code

A credit code adds prepaid usage credit to your organization. The credit shows up in `prepaid_credit` on the [balance](#check-the-balance) and pays for usage from the moment it is redeemed.

Only an organization owner or admin can redeem a code. An API key redeems with the authority of the user who created it (or the member it was transferred to), based on that user's current role, so use a key created by an owner or admin. A key that was transferred to another member without being rotated cannot redeem (`403`, reason `key_transferred_unrotated`): rotate it and use its successor.


```
primitive credits redeem LAUNCH50
primitive credits balance
```

```
curl -X POST https://api.primitive.dev/v1/credits/redeem \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: redeem-launch50-001" \
  -d '{"code": "LAUNCH50"}'
```


The CLI generates the `Idempotency-Key` for you. Over the API the header is **required**: 1 to 200 printable ASCII characters, without spaces. Retrying with the same key and code returns the original grant with `replayed: true` and adds no second credit; the same key with a different code is refused with `idempotency_key_reused`, so use a new key for each code.


```
{
  "success": true,
  "data": {
    "redemption_id": "...",
    "amount_micros": "50000000",
    "currency": "usd",
    "granted_at": "2026-09-23T17:00:00.000Z",
    "expires_at": "2026-12-31T00:00:00.000Z",
    "label": null,
    "replayed": false,
    "message": "$50.00 in credits added. Expires Dec 31, 2026. Applies to usage from now on."
  }
}
```


`expires_at` is `null` when the credit does not expire. `message` is a ready-to-show summary of the grant.

A refused redemption uses the standard [error envelope](/docs/errors), and its `error.message` is written to be shown to the user as is:

Status`error.code`Meaning400`idempotency_key_required`The `Idempotency-Key` header is missing.400`validation_error`The `Idempotency-Key` is empty, longer than 200 characters, or contains anything other than printable ASCII without spaces, or the body is invalid.409`credit_code_already_redeemed`Your organization or user already redeemed this code, or another code in the same exclusive group (a set of codes of which each organization or user may redeem only one).422`credit_code_invalid`The code is unknown, expired or used up, or the caller cannot redeem codes for the organization.422`credit_code_not_eligible`The organization does not meet the terms of the promotion.422`credit_code_balance_cap`The organization already holds the most promotional credit it can. Use some before redeeming another code.422`idempotency_key_reused`This `Idempotency-Key` already redeemed a different code.429`rate_limited`Too many requests or attempts. Wait for `Retry-After` and try again.503`service_unavailable`The code could not be redeemed right now. Retry later with the same `Idempotency-Key`.

The CLI prints the grant (amount and expiry) on success. On a refusal it prints the `error.message` and exits non-zero.

## Endpoint reference

OperationMethod and pathGet credit balance`GET /v1/credits/balance`Redeem a credit code`POST /v1/credits/redeem`

See the [API reference](/docs/api) for full request and response schemas, [Limits](/docs/limits) for rate constraints, [Errors](/docs/errors) for failure codes, and the [CLI](/docs/cli) page for command-line usage. Pricing for usage that credits pay for is on the [pricing page](/pricing).

Maintained by the [primitive.dev team](/about) · [Trust & security](/trust)Last updated: May 17, 2026