Skip to main content
GET
/
v1
/
contracts
/
{contractId}
/
credits
/
balance
Get Credit Balance and Blocks
curl --request GET \
  --url https://api.monk.com/v1/contracts/{contractId}/credits/balance \
  --header 'Authorization: Bearer <token>'
{
  "data": {
    "balance": {
      "balanceCents": 155000,
      "creditBalance": 1550,
      "currency": "USD",
      "blockCount": 2,
      "asOf": "2026-03-03T10:00:00.000Z"
    },
    "blocks": [
      {
        "id": "block-promo-1",
        "status": "active",
        "priority": 1,
        "daysUntilExpiry": 101,
        "originalCents": 20000,
        "originalCredits": 2000,
        "remainingCents": 15500,
        "remainingCredits": 1550,
        "creditRateCents": 10,
        "currency": "USD",
        "description": "Initial prepaid credit grant from contract creation",
        "isPromotional": false,
        "expiresAt": "2026-06-12T23:59:59.000Z",
        "createdAt": "2026-02-27T06:41:00.000Z"
      },
      {
        "id": "block-paid-1",
        "status": "depleted",
        "priority": null,
        "daysUntilExpiry": 101,
        "originalCents": 5000,
        "originalCredits": 500,
        "remainingCents": 0,
        "remainingCredits": 0,
        "creditRateCents": 10,
        "currency": "USD",
        "description": "Bonus credit grant from contract creation",
        "isPromotional": true,
        "expiresAt": "2026-06-12T23:59:59.000Z",
        "createdAt": "2026-02-27T06:41:00.000Z"
      }
    ]
  }
}
Returns the aggregate credit balance and all credit blocks (grants) for a contract. Returns zero balance with empty blocks if no credit wallet exists. Block Status:
StatusDescription
activeBlock has remaining balance and is not expired
depletedBlock balance has been fully consumed
expiredBlock has passed its expiration date
FIFO Deduction Priority: Active blocks include a priority field (1 = first to deduct) based on:
  1. Soonest expiring first
  2. Promotional before paid
  3. Lowest cost basis (rate)
  4. Oldest first (FIFO)
Scope: contracts:read

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
contractId
string
required

The unique identifier of the contract (UUID)

Response

Credit balance and blocks

​
data
object

Credit wallet balance and blocks