---
title: "Tenant-wide ledger"
method: GET
path: "/credits/ledger"
tags: ["Ledger"]
---

# Tenant-wide ledger

`GET /credits/ledger`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/ledger`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Lists double-entry ledger entries across the whole workspace, newest first, with cursor pagination. Filter by category, end user, initiator, provider and endpoint, creation window, attribution keys, ledger event kind, or the pooled platform account.

## Query parameters

- `category` 'TOPUP' | 'BURN' | 'REFUND' | 'CLAWBACK' | 'FEE' | 'ADJUSTMENT' | 'ALLOCATION' | 'PROMO'
- `externalUserId` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.
- `initiator` string
- `provider` string
- `endpoint` string
- `createdAfter` string, date-time
- `createdBefore` string, date-time
- `attribution.{key}` string
- `sourceKey` string
- `account` 'platform'
- `cursor` string
- `limit` integer

## Response `200`

Ledger page

- TenantLedgerPage
  - `success` true, required
  - `entries` LedgerEntry[], required
    - `id` string, uuid, required
    - `direction` 'DEBIT' | 'CREDIT', required
    - `category` string, required
    - `amountUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `amountCredits` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `balanceAfterUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `baseUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `marginUsdc` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `markupBps` integer, nullable, required
    - `sourceKey` string, required
    - `externalReference` string, nullable, required
    - `externalUserId` string, nullable, required
    - `metadata` unknown, required
    - `createdAt` string, date-time, required
  - `nextCursor` string, nullable, required
  - `customers` CustomerName[], required: Directory names for the customers this page's entries were attributed to.
    - `spenderId` string, required: The customer's spender id: <URL-encoded source>/<customerId>.
    - `source` string, required
    - `customerId` string, required
    - `name` string, required
    - `url` string, nullable, required
    - `adminUrl` string, nullable, required
  - `appliedFilters` string[], required: Names of the narrowing query filters this server applied. An empty array means the request did not include a narrowing filter.

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)