---
title: "Balance, limits, allowance and recent ledger"
method: GET
path: "/v1/credits"
tags: ["Account"]
---

# Balance, limits, allowance and recent ledger

`GET /v1/credits`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/credits`
- Auth: HTTP bearer

Balance is read from the append-only ledger. `funding.cash_on_hand_credits` is money that has cleared; a top-up is spendable immediately but an order is only SENT to a supplier once the money behind it settles. `read_allowance` shows the monthly row entitlement before a 429. `refund` shows what an unspent balance would return today.

## Response `200`

OK

- object
  - `balance_credits` integer: Credits. 1 credit = 1 US cent.
  - `funding` object, nullable
    - `cash_on_hand_credits` integer
    - `pending_credits` integer
    - `settles_immediately` boolean
    - `hold_hours` integer
  - `read_allowance` object
    - `rows_used_this_month` integer
    - `rows_allowed_this_month` integer
    - `note` string
  - `balance_usd` string: Credits are pegged 1:1 to US cents, so this is exact.
  - `limits` object
    - `per_order_max_credits` integer, nullable
    - `daily_max_credits` integer, nullable
    - `spent_today_credits` integer
    - `remaining_today_credits` integer, nullable
  - `refund_grace_days` integer, nullable: The account grace period, in days, applied once. On timing alone an undelivered order is flagged `refund_eligible` from due_at plus one account grace period. A credit refund for an order already with a supplier is guarded separately by due_at plus the supplier's refund window plus that same one account grace period, and it also requires that we have recovered from the supplier, unless we choose to bridge it as a goodwill decision. Passing the timing threshold alone never returns credits.
  - `volume_credits_earned` integer
  - `refund` object
    - `refundable_credits` integer
    - `fee_credits` integer
    - `payout_credits` integer
    - `eligible` boolean
    - `reason` string, nullable
    - `window_days` integer
    - `note` string
  - `recent_entries` object[]
    - `entry_id` integer
    - `kind` string
    - `amount_credits` integer
    - `order_id` string, nullable
    - `memo` string, nullable
    - `receipt_url` string, nullable
    - `created_at` string

## Other responses

- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `403`: `insufficient_scope` when the key lacks the `order` scope; `customer_key_required` when the operator token is used where a customer must be attributable.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)