Skip to content
Indiana
Dashboard
Docs
Browse docs / Read customer ledger

Read customer ledger

POST/api/v1/customer-ledger

Query verified financial facts by type and date across history.

SDK 0.0.1Updated

Make the request

Query verified financial facts by type and date across history.

Credential
Server API key or customer token. Customer calls cannot select another customer.
Permission
credits:read
Set the base URL and App ID from SDK setup. These examples use placeholders and do not execute requests. Never put a server key in browser code.
request.shShell
curl -X POST "$GROOVE_BASE_URL/api/v1/customer-ledger" \  -H "Authorization: Bearer $GROOVE_CUSTOMER_TOKEN" \  -H "X-Groove-Project: $GROOVE_PROJECT_ID" \  -H "X-Groove-Environment: sandbox" \  -H "Content-Type: application/json" \  -d '{  "query": {    "type": null,    "from": null,    "to": null,    "after": null,    "limit": 50  }}'

The response tab lists field types, not an example payload. Actual values depend on customer state.

Request parameters

JSON body

customerIduuidOptional

Indiana customer ID mapped from a verified identity on the server. Omit for customer-token calls, which use the token-bound customer.

queryobjectRequired

The query value for this operation. Its accepted type and constraints are listed above and below.

Show child fields
typeenum | nullRequired

The type value for this operation. Its accepted type and constraints are listed above and below.

fromdate | nullRequired

The from value for this operation. Its accepted type and constraints are listed above and below.

todate | nullRequired

The to value for this operation. Its accepted type and constraints are listed above and below.

afterobject | nullRequired

The after value for this operation. Its accepted type and constraints are listed above and below.

Show child fields
atdate-timeRequired

The at value for this operation. Its accepted type and constraints are listed above and below.

iduuidRequired

The id value for this operation. Its accepted type and constraints are listed above and below.

typeenumRequired

The type value for this operation. Its accepted type and constraints are listed above and below.

Show allowed values

"source""usage""transaction""debt""settlement"

limitintegerRequired

Maximum records per page, subject to the contract limit.

min: 1 · max: 50

Response fields

Successful responses include requestId and scope. Use the actual business status or accepted field to determine the result. Optional fields are omitted when unavailable.

HTTP 200 · application/json

requestIduuidRequired

Server-generated HTTP request UUID. Include it when reporting a failed request.

scopeobjectRequired

The App and environment of this response. Headers only verify scope; they cannot switch key scope.

Show child fields
projectIdstringRequired

App ID bound to the credential.

minLength: 1

environmentenumRequired

Separate data scope: sandbox or live.

Show allowed values

"sandbox""live"

ledgerobjectRequired

The ledger value for this operation. Its accepted type and constraints are listed above and below.

Show child fields
customerIduuidRequired

Indiana customer ID mapped from a verified identity on the server. Omit for customer-token calls, which use the token-bound customer.

rowsarrayRequired

The rows value for this operation. Its accepted type and constraints are listed above and below.

maxItems: 50

Show child fields
iduuid | uuid | uuid | uuid | uuidRequired

The id value for this operation. Its accepted type and constraints are listed above and below.

occurredAtdate-time | date-time | date-time | date-time | date-timeRequired

The occurredAt value for this operation. Its accepted type and constraints are listed above and below.

entitlementIduuid | uuid | uuid | uuidOptional

The entitlementId value for this operation. Its accepted type and constraints are listed above and below.

entitlementVersionIduuid | uuid | uuidOptional

The entitlementVersionId value for this operation. Its accepted type and constraints are listed above and below.

versioninteger | integer | integerOptional

The version value for this operation. Its accepted type and constraints are listed above and below.

keystring | string | stringOptional

The key value for this operation. Its accepted type and constraints are listed above and below.

namestring | string | string | stringOptional

Display name of the customer or object; not an identity key.

kindenum | enum | enum | enum | enumRequired

The kind value for this operation. Its accepted type and constraints are listed above and below.

type"source" | "usage" | "transaction" | "debt" | "settlement"Required

The type value for this operation. Its accepted type and constraints are listed above and below.

reasonenum | enum | nullOptional

Rejection reason or ledger operation description; interpret with accepted and status.

quantitystring | objectOptional

Use the declared field type for business quantity. Credit operations use decimal strings to avoid floating-point error. quote/reserve/confirm/refund require positive quantities; consume can record zero-cost events.

unlimitedbooleanOptional

The unlimited value for this operation. Its accepted type and constraints are listed above and below.

statusenumOptional

The status value for this operation. Its accepted type and constraints are listed above and below.

Show allowed values

"scheduled""active""expired""revoked""unavailable"

startsAtdate-timeOptional

The startsAt value for this operation. Its accepted type and constraints are listed above and below.

expiresAtdate-time | null | date-time | nullOptional

ISO 8601 UTC expiry. Expired sessions and reservations cannot be reused.

orderIduuid | null | uuidOptional

The orderId value for this operation. Its accepted type and constraints are listed above and below.

parentSourceIduuid | nullOptional

The parentSourceId value for this operation. Its accepted type and constraints are listed above and below.

originalIduuid | null | uuid | nullOptional

The originalId value for this operation. Its accepted type and constraints are listed above and below.

acceptedbooleanOptional

Whether business rules accepted the operation. HTTP 200 does not imply accepted is true.

propertiesobjectOptional

Validated pricing properties used to match dimensions and multipliers.

reservationStatusenum | nullOptional

The reservationStatus value for this operation. Its accepted type and constraints are listed above and below.

chargesarrayOptional

The charges value for this operation. Its accepted type and constraints are listed above and below.

maxItems: 500

Show child fields
entitlementIduuidOptional

The entitlementId value for this operation. Its accepted type and constraints are listed above and below.

entitlementVersionIduuidOptional

The entitlementVersionId value for this operation. Its accepted type and constraints are listed above and below.

versionintegerOptional

The version value for this operation. Its accepted type and constraints are listed above and below.

max: 9007199254740991

keystringOptional

The key value for this operation. Its accepted type and constraints are listed above and below.

minLength: 1 · maxLength: 64

namestringOptional

Display name of the customer or object; not an identity key.

minLength: 1 · maxLength: 120

kindenumOptional

The kind value for this operation. Its accepted type and constraints are listed above and below.

Show allowed values

"access""metered""credit"

funding"prepaid" | "postpaid"Required

The funding value for this operation. Its accepted type and constraints are listed above and below.

amountstringOptional

Credit or ledger amount, using the field’s decimal-string or integer type.

pattern: ^(0|[1-9]\d{0,17})(\.\d{1,12})?$

invoiceIduuidOptional

The invoiceId value for this operation. Its accepted type and constraints are listed above and below.

invoiceLineIduuidOptional

The invoiceLineId value for this operation. Its accepted type and constraints are listed above and below.

authorizationIduuidOptional

The authorizationId value for this operation. Its accepted type and constraints are listed above and below.

unitsobjectOptional

The units value for this operation. Its accepted type and constraints are listed above and below.

currencyenumOptional

Currency code supported by the published price.

Show allowed values

"USD""EUR""CNY""GBP""JPY""CAD""AUD""NZD""CHF""HKD""SGD""KRW""INR""BRL""MXN""TWD""THB""IDR""MYR""PHP""VND""ZAR""AED""SAR""SEK""NOK""DKK""PLN""CZK""HUF""ILS""TRY""RON"

purposeenumOptional

The purpose value for this operation. Its accepted type and constraints are listed above and below.

Show allowed values

"product""invoice"

productVersionIduuid | nullOptional

The productVersionId value for this operation. Its accepted type and constraints are listed above and below.

productNamestring | nullOptional

The productName value for this operation. Its accepted type and constraints are listed above and below.

productVersioninteger | nullOptional

The productVersion value for this operation. Its accepted type and constraints are listed above and below.

invoiceIduuid | nullOptional

The invoiceId value for this operation. Its accepted type and constraints are listed above and below.

amountMinorinteger | nullOptional

The amountMinor value for this operation. Its accepted type and constraints are listed above and below.

currencyenum | nullOptional

Currency code supported by the published price.

sourceIduuid | uuidOptional

The sourceId value for this operation. Its accepted type and constraints are listed above and below.

transactionIduuidOptional

Ledger transaction UUID from the original consumption, referenced by a refund.

amountstring | stringOptional

Credit or ledger amount, using the field’s decimal-string or integer type.

debtIduuidOptional

The debtId value for this operation. Its accepted type and constraints are listed above and below.

nextCursorobject | nullRequired

Next-page cursor; null means end. Pass unchanged and clear when filters change.

Show child fields
atdate-timeRequired

The at value for this operation. Its accepted type and constraints are listed above and below.

iduuidRequired

The id value for this operation. Its accepted type and constraints are listed above and below.

typeenumRequired

The type value for this operation. Its accepted type and constraints are listed above and below.

Show allowed values

"source""usage""transaction""debt""settlement"

Handle errors

Common failures
CodeRecovery
UNAUTHENTICATEDVerify the key or refresh the expired customer token once.
FORBIDDENCheck current key permissions and customer access.
INVALID_REQUESTCheck field types, UUIDs, decimal strings and mutually exclusive fields.
SCOPE_MISMATCHUse the App and environment bound to the credential.

Common failures

  • UNAUTHENTICATED

    Recovery
    Verify the key or refresh the expired customer token once.

  • FORBIDDEN

    Recovery
    Check current key permissions and customer access.

  • INVALID_REQUEST

    Recovery
    Check field types, UUIDs, decimal strings and mutually exclusive fields.

  • SCOPE_MISMATCH

    Recovery
    Use the App and environment bound to the credential.

Related:All request and error conventions·Back to endpoint index