@dodopayments/opencode-plugin 0.3.3 → 0.4.0

package/skills/credit-based-billing/SKILL.md

@@ -1,942 +1,615 @@
 ---
 name: credit-based-billing
-description: Guide for implementing credit-based billing with Dodo Payments - credit entitlements, balances, ledger management, rollover, overage, and meter-based deduction.
+description: Complete guide for giving customers included, free, prepaid, promotional, or top-up credits using grants, balances, ledger deductions, rollover, expiry, alerts, and overage.
 ---
 
 # Dodo Payments Credit-Based Billing
 
-**Reference: [docs.dodopayments.com/features/credit-based-billing](https://docs.dodopayments.com/features/credit-based-billing)**
+Use this skill to build prepaid or included-credit billing for tokens, API calls, compute, storage, or currency-denominated value, with auditable grants and deductions.
 
-Grant customers a balance of credits (API calls, tokens, compute units, or any custom metric) and deduct from that balance as they consume your service.
+## When to use this skill
 
----
+- Include a recurring credit allowance in a subscription.
+- Sell one-time top-up packs or prepaid usage.
+- Deduct credits from metered AI, API, or compute consumption.
+- Grant promotional or support credits and record a reason.
+- Configure expiry, rollover, low-balance alerts, or overage.
+- Reconcile a customer's balance against an immutable ledger trail.
 
-## Overview
+## Choose the billing model
 
-Credit-based billing lets you:
-- **Issue credits** with subscriptions, one-time purchases, or via API
-- **Deduct automatically** via usage meters or manually via API
-- **Configure rollover** to carry unused credits forward
-- **Handle overage** when credits run out mid-cycle
-- **Set expiration** rules per credit entitlement
-- **Track everything** via a full audit ledger
+| Requirement | Choose | Why |
+|---|---|---|
+| A fixed product with no tracked consumption | Plain subscription or one-time payment | No balance or usage pipeline is needed. |
+| Bill each measured unit directly in money | Pure usage-based billing | A meter rates usage with `price_per_unit`; no prepaid pool is needed. |
+| Include or pre-sell a consumable allowance | Credit-based billing | Grants create a balance that usage can consume. |
+| Include credits, then charge beyond the allowance | Credits with overage | The credit pool is consumed first; configured overage handles the deficit. |
+| Combine a base fee, included credits, and metered use | Usage-based product linked to a credit entitlement | The meter converts usage units into credit deductions. |
 
-Credits work across all product types: subscriptions, one-time purchases, and usage-based billing.
+Credit-based and usage-based billing are complementary. Define and test meters with the `usage-based-billing` skill; this skill covers the credit side and the meter-to-credit link.
 
----
+## Core concepts
 
-## Core Concepts
+### Credit entitlements and grants
 
-### Credit Types
+A **credit entitlement** is the reusable definition of a credit unit and its lifecycle: name, unit, precision, expiry, rollover, and overage. A **grant** is an issuance of that credit to one customer. Grants can originate from:
 
-| Type | Description | Best For |
-|------|-------------|----------|
-| **Custom Unit** | Your own metric (tokens, API calls, compute hours) with configurable precision (0–3 decimals) | API calls, AI tokens, compute hours, messages |
-| **Fiat Credits** | Real currency value (USD, EUR, etc.) that depletes as customers use your service | Prepaid balances, promotional credits, compensation |
+- a subscription, reissued each billing cycle;
+- a one-time product or add-on;
+- a direct API ledger credit;
+- rollover from an earlier grant.
 
-### Credit Lifecycle
+Credits gate **how much** a customer can consume. The separate `entitlements` resource gates fulfillment such as feature access, files, or license delivery. Do not confuse these SDK namespaces:
 
-1. **Credits Issued** — Granted on purchase (subscription cycle or one-time) or via API
-2. **Credits Consumed** — Deducted via meter events or manual API calls
-3. **Credits Expire or Roll Over** — At cycle end, unused credits expire or carry forward
-4. **Overage Handling** — If balance hits zero, overage is forgiven, billed, or carried as deficit
+```text
+client.creditEntitlements             credit definitions and balances
+client.creditEntitlements.balances    customer credit balances and ledger
+client.entitlements                   feature/file/license entitlements
+client.entitlements.files             entitlement files
+client.entitlements.grants            fulfillment grants
+```
 
-### Grant Sources
+Use `client.customers.listCreditEntitlements(customerID)` for the customer-level credit-entitlement view. Do not substitute `client.customers.listEntitlements(...)`, which reads the other entitlement system.
 
-| Source | Description |
-|--------|-------------|
-| **Subscription** | Credits issued each billing cycle |
-| **One-Time** | Credits issued with a one-time payment |
-| **API** | Credits granted manually via API or dashboard |
-| **Rollover** | Credits carried over from a previous billing cycle |
+### Custom-unit and fiat credits
 
----
+| Credit model | Representation | Example |
+|---|---|---|
+| Custom unit | Application-defined units | tokens, calls, compute hours, GB-hours |
+| Fiat | Currency value | USD or EUR prepaid balance |
 
-## Quick Start
+Custom-unit precision is configurable from `0` through `10`; the dashboard default is `2`. Precision cannot be changed after creation, so choose it before issuing grants. Use `0` for indivisible units such as whole requests. Use decimal precision only when fractional credits are meaningful.
 
-### 1. Create a Credit Entitlement
+Fiat examples use currency minor units: `5,000` credits represents USD 50 in the documented OpenAI example. Do not infer a universal fiat precision rule beyond the documented minor-unit model. All monetary amounts are in the currency's smallest unit (for example, cents for USD).
 
-```typescript
-import DodoPayments from 'dodopayments';
+A product can carry up to **five** credit entitlements. Each can have independent issuance and lifecycle settings.
 
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
-});
+### Balance and ledger
 
-const credit = await client.creditEntitlements.create({
-  name: 'API Credits',
-  credit_type: 'custom_unit',
-  unit_name: 'API Calls',
-  precision: 0,
-  expiry_duration: 30, // days
-  rollover_enabled: false,
-  allow_overage: false,
-});
-```
-
-### 2. Attach Credits to a Product
+The balance response includes `balance`, `overage`, `last_transaction_at`, identifiers, and timestamps. Treat credit amounts as decimal strings; do not pass them through binary floating-point arithmetic.
 
-In Dashboard → Products → Create/Edit Product → Entitlements → Attach Credits:
-- Select the credit entitlement
-- Set credits issued per billing cycle (subscriptions) or total (one-time)
-- Configure trial credits, proration, low balance threshold
-
-### 3. Create Checkout with Credit Product
-
-```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [
-    {
-      product_id: 'prod_ai_pro_plan', // Product with credits attached
-      quantity: 1,
-    }
-  ],
-  customer: { email: 'customer@example.com' },
-  return_url: 'https://yourapp.com/success',
-});
+Every transaction has a ledger record with:
 
-// Redirect to session.checkout_url
-```
+- `balance_before` and `balance_after`;
+- `overage_before` and `overage_after`;
+- amount and transaction type;
+- source references and grant ID;
+- description, metadata, and timestamp.
 
-### 4. Deduct Credits via Usage Events
+This ledger is the audit trail and provides transaction-level balance snapshots. There is no separately documented historical balance-snapshots endpoint.
 
-```typescript
-// Meter linked to credit entitlement deducts automatically
-await client.usageEvents.ingest({
-  events: [{
-    event_id: `gen_${Date.now()}_${crypto.randomUUID()}`,
-    customer_id: 'cus_abc123',
-    event_name: 'ai.generation',
-    timestamp: new Date().toISOString(),
-    metadata: { model: 'gpt-4', tokens: '1500' }
-  }]
-});
-```
+## Initialize the TypeScript SDK
 
-### 5. Check Balance
+Keep API keys server-side. Dodo Payments keys use `dodo_test_...` and `dodo_live_...` prefixes.
 
 ```typescript
-const balance = await client.creditEntitlements.balances.get(
-  'cent_credit_id',
-  'cus_abc123'
-);
+import DodoPayments from 'dodopayments';
 
-console.log(`Available: ${balance.available_balance}`);
-console.log(`Overage: ${balance.overage_balance}`);
+const client = new DodoPayments({
+  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
+  environment: 'test_mode',
+});
 ```
 
----
-
-## API Reference
-
-### Credit Entitlement CRUD
-
-| Operation | Method | Endpoint |
-|-----------|--------|----------|
-| Create | `POST` | `/credit-entitlements` |
-| List | `GET` | `/credit-entitlements` |
-| Get | `GET` | `/credit-entitlements/{id}` |
-| Update | `PATCH` | `/credit-entitlements/{id}` |
-| Delete | `DELETE` | `/credit-entitlements/{id}` |
-| Undelete | `POST` | `/credit-entitlements/{id}/undelete` |
-
-### Balance & Ledger Operations
-
-| Operation | Method | Endpoint |
-|-----------|--------|----------|
-| List All Balances | `GET` | `/credit-entitlements/{id}/balances` |
-| Get Customer Balance | `GET` | `/credit-entitlements/{id}/balances/{customer_id}` |
-| Create Ledger Entry | `POST` | `/credit-entitlements/{id}/balances/{customer_id}/ledger-entries` |
-| List Customer Ledger | `GET` | `/credit-entitlements/{id}/balances/{customer_id}/ledger` |
-| List Customer Grants | `GET` | `/credit-entitlements/{id}/balances/{customer_id}/grants` |
-
----
+The SDK defaults to `live_mode` when `environment` is omitted. Use `test_mode` explicitly during development.
 
-## Implementation Examples
+## Create and configure a credit entitlement
 
-### TypeScript/Node.js
-
-#### Create Credit Entitlement
+The confirmed TypeScript method is `client.creditEntitlements.create(...)`.
 
 ```typescript
 import DodoPayments from 'dodopayments';
 
 const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
+  environment: 'test_mode',
 });
 
-// Custom unit credit (AI tokens)
-const tokenCredit = await client.creditEntitlements.create({
-  name: 'AI Tokens',
-  credit_type: 'custom_unit',
-  unit_name: 'tokens',
+const tokenCredits = await client.creditEntitlements.create({
+  name: 'AI Token Credits',
+  description: 'Credits consumed by model token usage',
+  unit: 'token credit',
   precision: 0,
-  expiry_duration: 30,
+  expires_after_days: 30,
   rollover_enabled: true,
-  max_rollover_percentage: 25,
-  rollover_timeframe: 'month',
-  max_rollover_count: 3,
-  allow_overage: true,
-  overage_limit: 50000,
-  price_per_unit: 0.001,
-  overage_behavior: 'bill_overage_at_billing',
+  rollover_percentage: 25,
+  rollover_timeframe_count: 1,
+  rollover_timeframe_interval: 'Month',
+  max_rollover_count: 2,
+  overage_enabled: true,
+  overage_behavior: 'invoice_at_billing',
+  overage_limit: 100000,
+  price_per_unit: '1',
+  currency: 'USD',
 });
 
-// Fiat credit (USD balance)
-const usdCredit = await client.creditEntitlements.create({
-  name: 'Platform Credits',
-  credit_type: 'fiat',
-  unit_currency: 'USD',
-  expiry_duration: 90,
-  rollover_enabled: false,
-  allow_overage: false,
-});
+console.log(tokenCredits.id);
 ```
 
-#### Manual Credit/Debit via Ledger Entry
+`price_per_unit` is a decimal string in the configured currency; monetary values use the currency's smallest unit. In this example, `'1'` is one cent per overage credit for USD.
 
-```typescript
-// Grant credits manually (e.g., promotional bonus)
-await client.creditEntitlements.balances.createLedgerEntry(
-  'cent_credit_id',
-  'cus_abc123',
-  {
-    type: 'credit',
-    amount: '500',
-    description: 'Welcome bonus - 500 free API credits',
-    idempotency_key: `welcome_bonus_${customerId}`,
-  }
-);
+### Confirmed create options
 
-// Debit credits manually (e.g., service compensation deduction)
-await client.creditEntitlements.balances.createLedgerEntry(
-  'cent_credit_id',
-  'cus_abc123',
-  {
-    type: 'debit',
-    amount: '100',
-    description: 'Manual deduction for premium support',
-    idempotency_key: `support_deduction_${Date.now()}`,
-  }
-);
-```
+| Field | Required | Meaning and constraints |
+|---|---:|---|
+| `name` | Yes | Display name for the credit entitlement. |
+| `unit` | Yes | Unit label such as `API Calls`, `Tokens`, or `Credits`. |
+| `precision` | Yes | Decimal places, `0–10`; immutable after creation. |
+| `description` | No | Optional description. |
+| `expires_after_days` | No | Nullable number of days after issuance before expiry. |
+| `rollover_enabled` | Yes | Enables or disables carry-forward. |
+| `rollover_percentage` | No | Percentage carried forward, `0–100`. |
+| `rollover_timeframe_count` | No | Number of rollover-validity intervals. |
+| `rollover_timeframe_interval` | No | `Day`, `Week`, `Month`, or `Year`. |
+| `max_rollover_count` | No | Maximum consecutive rollovers before forfeiture. |
+| `overage_enabled` | Yes | Allows deficit handling after credits are exhausted. |
+| `overage_behavior` | No | End-of-cycle behavior from the exact enum below. |
+| `overage_limit` | No | Maximum allowed overage units. |
+| `price_per_unit` | Conditional | Decimal string; required when overage is enabled. |
+| `currency` | Conditional | Required when a price is present. Monetary values use the smallest currency unit. |
 
-#### Query Customer Balance and Ledger
+### Configure rollover
 
-```typescript
-// Get current balance
-const balance = await client.creditEntitlements.balances.get(
-  'cent_credit_id',
-  'cus_abc123'
-);
-console.log(`Balance: ${balance.available_balance}`);
+Rollover carries eligible unused credits into a new grant. Configure:
 
-// List all balances for a credit entitlement
-const allBalances = await client.creditEntitlements.balances.list(
-  'cent_credit_id'
-);
+1. `rollover_enabled: true`.
+2. `rollover_percentage` as the carry-forward cap from `0` through `100`.
+3. Both `rollover_timeframe_count` and `rollover_timeframe_interval`; neither should be supplied alone.
+4. `max_rollover_count` if credits may roll only a limited number of consecutive times.
 
-// Get full transaction history
-const ledger = await client.creditEntitlements.balances.listLedger(
-  'cent_credit_id',
-  'cus_abc123'
-);
+Rollover is applied before expiry; only the remainder expires.
 
-for (const entry of ledger.items) {
-  console.log(`${entry.type}: ${entry.amount} | Balance: ${entry.balance_after}`);
-}
+### Configure expiry
 
-// List credit grants
-const grants = await client.creditEntitlements.balances.listGrants(
-  'cent_credit_id',
-  'cus_abc123'
-);
-```
+The API represents expiry as nullable `expires_after_days`. The dashboard offers 7, 30, 60, 90, custom days, or never; its default is 30 days, and custom expiry has a one-day minimum. Use `null` for no API-configured expiry only where the current API form permits it.
 
-#### Update Credit Entitlement Settings
+### Configure overage
 
-```typescript
-await client.creditEntitlements.update('cent_credit_id', {
-  rollover_enabled: true,
-  max_rollover_percentage: 50,
-  allow_overage: true,
-  overage_limit: 10000,
-  price_per_unit: 0.002,
-  overage_behavior: 'bill_overage_at_billing',
-});
-```
+| Exact `overage_behavior` value | Result at billing-cycle end |
+|---|---|
+| `forgive_at_reset` | Do not charge and do not preserve the deficit. This is the default. |
+| `invoice_at_billing` | Charge the overage at billing, then reset it. |
+| `carry_deficit` | Preserve the negative balance. |
+| `carry_deficit_auto_repay` | Preserve the deficit and repay it from newly issued credits. |
 
-### Python
-
-```python
-from dodopayments import DodoPayments
-import os
-import uuid
-from datetime import datetime
-
-client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
-
-# Create credit entitlement
-credit = client.credit_entitlements.create(
-    name="AI Tokens",
-    credit_type="custom_unit",
-    unit_name="tokens",
-    precision=0,
-    expiry_duration=30,
-    rollover_enabled=True,
-    max_rollover_percentage=25,
-    allow_overage=True,
-    overage_limit=50000,
-    price_per_unit=0.001,
-    overage_behavior="bill_overage_at_billing",
-)
-
-# Grant credits manually
-client.credit_entitlements.balances.create_ledger_entry(
-    credit_entitlement_id="cent_credit_id",
-    customer_id="cus_abc123",
-    type="credit",
-    amount="500",
-    description="Promotional bonus",
-    idempotency_key=f"promo_{uuid.uuid4()}",
-)
-
-# Check balance
-balance = client.credit_entitlements.balances.get(
-    credit_entitlement_id="cent_credit_id",
-    customer_id="cus_abc123",
-)
-print(f"Available: {balance.available_balance}")
-
-# Send usage events that deduct credits
-client.usage_events.ingest(events=[{
-    "event_id": f"api_{datetime.now().timestamp()}_{uuid.uuid4()}",
-    "customer_id": "cus_abc123",
-    "event_name": "ai.tokens",
-    "timestamp": datetime.now().isoformat(),
-    "metadata": {"tokens": "1500", "model": "gpt-4"}
-}])
-```
+When `overage_enabled` is true, `price_per_unit` is required; when a price is present, `currency` is required. Use `overage_limit` to cap allowed overage units.
 
-### Go
-
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "os"
-    "time"
-
-    "github.com/dodopayments/dodopayments-go"
-    "github.com/google/uuid"
-)
-
-func main() {
-    client := dodopayments.NewClient(
-        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
-    )
-
-    ctx := context.Background()
-
-    // Create credit entitlement
-    credit, err := client.CreditEntitlements.Create(ctx, &dodopayments.CreditEntitlementCreateParams{
-        Name:       "AI Tokens",
-        CreditType: "custom_unit",
-        UnitName:   "tokens",
-        Precision:  0,
-    })
-    if err != nil {
-        panic(err)
-    }
-
-    // Get customer balance
-    balance, err := client.CreditEntitlements.Balances.Get(ctx, credit.ID, "cus_abc123")
-    if err != nil {
-        panic(err)
-    }
-    fmt.Printf("Balance: %s\n", balance.AvailableBalance)
-
-    // Send usage events
-    _, err = client.UsageEvents.Ingest(ctx, &dodopayments.UsageEventIngestParams{
-        Events: []dodopayments.UsageEvent{{
-            EventID:    fmt.Sprintf("api_%d_%s", time.Now().Unix(), uuid.New().String()),
-            CustomerID: "cus_abc123",
-            EventName:  "ai.tokens",
-            Timestamp:  time.Now().Format(time.RFC3339),
-            Metadata: map[string]string{
-                "tokens": "1500",
-                "model":  "gpt-4",
-            },
-        }},
-    })
-    if err != nil {
-        panic(err)
-    }
-}
-```
+When overage is disabled, Dodo stops deducting after the balance reaches zero. Meter processing is asynchronous, so this is not synchronous authorization for your application requests. Implement application-side enforcement when requests must be rejected immediately.
 
----
+## Attach credits to products and subscriptions
 
-## Credit Settings
+Credits are attached to products as credit entitlements in the product creation or edit flow. Do not use `client.entitlements.grants` to attach or issue credit balances.
 
-### Rollover
+### Subscription product
 
-Carry unused credits forward to the next billing cycle:
+In **Products → Create Product** or an existing product:
 
-| Setting | Description |
-|---------|-------------|
-| **Rollover Enabled** | Toggle to allow unused credits to carry forward |
-| **Max Rollover Percentage** | Limit how much carries over (0–100%) |
-| **Rollover Timeframe** | How long rolled-over credits remain valid (day, week, month, year) |
-| **Max Rollover Count** | Maximum consecutive rollovers before credits are forfeited |
+1. Choose subscription pricing.
+2. Open **Entitlements & Credits** and attach an existing credit entitlement.
+3. Set the credits issued each billing period.
+4. Optionally set a low-balance notification amount, trial-credit amount, whether unused trial credits expire after trial, and credit proration for plan changes.
+5. Keep the entitlement's default rollover, overage, and expiry rules or customize them for this product.
 
-**Example**: 200 unused credits at cycle end, 75% rollover → 150 credits carry forward, 50 forfeited.
+The customer receives a fresh grant each billing cycle.
 
-### Overage
+### One-time product or add-on
 
-Controls what happens when a customer's balance reaches zero mid-cycle:
+Attach the credit entitlement to a single-payment product or add-on and configure the one-time amount. The purchase issues one grant. This is the supported shape for prepaid packs, top-ups, and promotional bundles.
 
-| Setting | Description |
-|---------|-------------|
-| **Allow Overage** | Let customers continue past zero balance |
-| **Overage Limit** | Max credits consumable beyond balance |
-| **Price Per Unit** | Cost per additional credit (with currency) |
-| **Overage Behavior** | How overage is handled at cycle end |
+### Usage-based product
 
-**Overage Behaviors:**
+Attach the credit entitlement to the same usage-based product as the meter. The confirmed meter attachment fields are:
 
-| Behavior | Description |
-|----------|-------------|
-| **Forgive overage at reset** | Overage tracked but not billed (default) |
-| **Bill overage at billing** | Overage charged on next invoice |
-| **Carry over deficit** | Negative balance carries into next cycle |
-| **Carry over deficit (auto-repay)** | Deficit auto-repaid from new credits next cycle |
+| Field | Purpose |
+|---|---|
+| `meter_id` | Meter to aggregate usage. |
+| `free_threshold` | Optional usage excluded before rating. |
+| `credit_entitlement_id` | Credit pool consumed by this meter. |
+| `meter_units_per_credit` | Usage units required to deduct one credit; required when `credit_entitlement_id` is set. |
+| `price_per_unit` | Direct per-unit monetary price when using pure usage pricing; decimal string. |
 
-### Expiration
+Product attachment request shapes can evolve. Configure them in the dashboard or copy the current schema from the [Create Product API](https://docs.dodopayments.com/api-reference/products/post-products); do not invent an `entitlements`, `credits`, or `grants` payload.
 
-| Setting | Description |
-|---------|-------------|
-| **Credit Expiry** | Duration after issuance: 7, 30, 60, 90, custom days, or never |
-| **Trial Credits Expire After Trial** | Whether trial-specific credits expire when trial ends |
+### Start checkout for an attached product
 
----
+Product purchase creates the customer grant; checkout does not accept an ad hoc credit amount.
 
-## Webhook Events
+```typescript
+const session = await client.checkoutSessions.create({
+  product_cart: [
+    {
+      product_id: 'pdt_ai_pro_plan',
+      quantity: 1,
+    },
+  ],
+  customer: { email: 'customer@example.com' },
+  return_url: 'https://app.example.com/billing/success',
+});
 
-Credit-based billing fires these webhook events:
+console.log(session);
+```
 
-| Event | Description |
-|-------|-------------|
-| `credit.added` | Credits granted to a customer |
-| `credit.deducted` | Credits consumed through usage or manual debit |
-| `credit.expired` | Unused credits expired |
-| `credit.rolled_over` | Credits carried forward to a new grant |
-| `credit.rollover_forfeited` | Credits forfeited at max rollover count |
-| `credit.overage_charged` | Overage charges applied |
-| `credit.manual_adjustment` | Manual credit/debit adjustment made |
-| `credit.balance_low` | Balance dropped below configured threshold |
+Use `checkoutSessions.create`, not the deprecated `payments.create` or `subscriptions.create` methods.
 
-### Webhook Handler Example
+## Discover a customer's credit entitlements
+
+Use the customer resource when the application needs to discover all credit entitlements associated with a customer:
 
 ```typescript
-// app/api/webhooks/dodo/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function POST(req: NextRequest) {
-  const event = await req.json();
-
-  switch (event.type) {
-    case 'credit.added':
-      await handleCreditAdded(event.data);
-      break;
-    case 'credit.deducted':
-      await handleCreditDeducted(event.data);
-      break;
-    case 'credit.balance_low':
-      await handleBalanceLow(event.data);
-      break;
-    case 'credit.expired':
-      await handleCreditExpired(event.data);
-      break;
-    case 'credit.overage_charged':
-      await handleOverageCharged(event.data);
-      break;
-  }
+const customerCredits = await client.customers.listCreditEntitlements(
+  'cus_TV52uJWWXt2yIoBBxpjaa',
+);
 
-  return NextResponse.json({ received: true });
-}
+console.log(customerCredits);
+```
 
-async function handleCreditAdded(data: any) {
-  const { customer_id, credit_entitlement_id, amount, balance_after } = data;
-  
-  // Update internal records
-  await prisma.creditBalance.upsert({
-    where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } },
-    create: { customerId: customer_id, creditId: credit_entitlement_id, balance: balance_after },
-    update: { balance: balance_after },
-  });
-}
+Use the balance resource below when the credit entitlement ID is already known and an exact balance is required.
 
-async function handleCreditDeducted(data: any) {
-  const { customer_id, credit_entitlement_id, amount, balance_after } = data;
+## Read a customer's balance
 
-  await prisma.creditBalance.update({
-    where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } },
-    data: { balance: balance_after },
-  });
-}
+The confirmed method takes the customer ID first and the credit entitlement ID inside the options object:
 
-async function handleBalanceLow(data: any) {
-  const {
-    customer_id,
-    credit_entitlement_name,
-    available_balance,
-    threshold_percent,
-  } = data;
-
-  // Notify the customer
-  await sendEmail(customer_id, {
-    subject: `Your ${credit_entitlement_name} balance is running low`,
-    body: `You have ${available_balance} credits remaining (${threshold_percent}% threshold reached). Consider upgrading your plan or purchasing additional credits.`,
-  });
-}
+```typescript
+const customerCreditBalance = await client.creditEntitlements.balances.retrieve(
+  'cus_TV52uJWWXt2yIoBBxpjaa',
+  { credit_entitlement_id: 'cde_ztxm5XJsKxWucRWA3rjdM' },
+);
 
-async function handleCreditExpired(data: any) {
-  const { customer_id, credit_entitlement_id, amount, balance_after } = data;
+console.log({
+  balance: customerCreditBalance.balance,
+  overage: customerCreditBalance.overage,
+  lastTransactionAt: customerCreditBalance.last_transaction_at,
+});
+```
 
-  await prisma.creditBalance.update({
-    where: { customerId_creditId: { customerId: customer_id, creditId: credit_entitlement_id } },
-    data: { balance: balance_after },
-  });
+`balance` and `overage` are decimal strings in the entitlement's credit unit. They are not currency amounts unless the entitlement itself represents fiat value.
 
-  // Optionally notify customer
-  await sendCreditExpiryNotification(customer_id, amount);
-}
+## Grant credits manually
 
-async function handleOverageCharged(data: any) {
-  const { customer_id, credit_entitlement_id, amount, overage_after } = data;
+Manual credits are appropriate for promotions, migrations, refunds implemented as credit, and support gestures. Use a stable idempotency key derived from the business operation so a retry cannot grant twice.
 
-  // Track overage for billing
-  await prisma.overageRecord.create({
-    data: {
-      customerId: customer_id,
-      creditId: credit_entitlement_id,
-      amount,
-      overageBalance: overage_after,
+```typescript
+async function grantSupportCredits(
+  customerId: string,
+  creditEntitlementId: string,
+  supportCaseId: string,
+): Promise<string> {
+  const entry = await client.creditEntitlements.balances.createLedgerEntry(
+    customerId,
+    {
+      credit_entitlement_id: creditEntitlementId,
+      amount: '500',
+      entry_type: 'credit',
+      expires_at: '2027-01-31T23:59:59Z',
+      idempotency_key: `support-credit:${supportCaseId}`,
+      reason: `Support gesture for case ${supportCaseId}`,
+      metadata: { support_case_id: supportCaseId },
     },
-  });
-}
-```
-
-### Balance Low Payload
-
-The `credit.balance_low` event has a distinct payload:
+  );
 
-```json
-{
-  "business_id": "bus_xxxxx",
-  "type": "credit.balance_low",
-  "timestamp": "2025-08-04T06:15:00.000000Z",
-  "data": {
-    "payload_type": "CreditBalanceLow",
-    "customer_id": "cus_xxxxx",
-    "subscription_id": "sub_xxxxx",
-    "credit_entitlement_id": "cent_xxxxx",
-    "credit_entitlement_name": "API Credits",
-    "available_balance": "15",
-    "subscription_credits_amount": "100",
-    "threshold_percent": 20,
-    "threshold_amount": "20"
-  }
+  return entry.id;
 }
 ```
 
----
-
-## Usage Billing with Credits
-
-When credits are linked to usage meters, meter events automatically deduct credits. A background worker processes events every minute, converts meter units to credits using your configured rate, and deducts using FIFO ordering (oldest grants first).
-
-### How It Works
+`amount` is a decimal string backed by `NUMERIC(38,28)`; its integer part must be below `10^10`. `expires_at` applies to credits. Keep the amount within the entitlement's configured precision.
 
-1. **Your app sends usage events** — Each event includes customer ID, event name, and metadata
-2. **Meters aggregate events** — Using Count, Sum, Max, Last, or Unique Count
-3. **Credits are deducted automatically** — Converted at your configured `meter_units_per_credit` rate
-4. **Overage is tracked** — If balance reaches zero and overage is enabled, usage continues
+If the same `idempotency_key` already exists, the API can return `409`. Treat that as a signal to reconcile the original operation, not as permission to generate a new key and retry the grant.
 
-### Meter-Credit Configuration
+## Deduct credits manually
 
-In Dashboard → Products → Usage-Based Product → Select Meter:
-1. Toggle **Bill usage in Credits**
-2. Select the credit entitlement
-3. Set **Meter units per credit** (e.g., 1000 API calls = 1 credit)
-4. Set **Free Threshold** (units free before credit deduction begins)
-
-### AI Token Billing Example
+Use the same method with `entry_type: 'debit'`. Debits consume the oldest grants first (FIFO) and can return `400` when the balance is insufficient.
 
 ```typescript
-import DodoPayments from 'dodopayments';
-
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-});
-
-// Track AI token usage — meter auto-deducts credits
-async function trackAIUsage(
+async function deductJobCredits(
   customerId: string,
-  promptTokens: number,
-  completionTokens: number,
-  model: string
-) {
-  const totalTokens = promptTokens + completionTokens;
-
-  await client.usageEvents.ingest({
-    events: [{
-      event_id: `ai_${Date.now()}_${crypto.randomUUID()}`,
-      customer_id: customerId,
-      event_name: 'ai.tokens',
-      timestamp: new Date().toISOString(),
-      metadata: {
-        tokens: totalTokens.toString(),
-        prompt_tokens: promptTokens.toString(),
-        completion_tokens: completionTokens.toString(),
-        model,
-      }
-    }]
-  });
-}
+  creditEntitlementId: string,
+  jobId: string,
+  amount: string,
+): Promise<{ balanceAfter: string; overageAfter: string }> {
+  const entry = await client.creditEntitlements.balances.createLedgerEntry(
+    customerId,
+    {
+      credit_entitlement_id: creditEntitlementId,
+      amount,
+      entry_type: 'debit',
+      idempotency_key: `job-debit:${jobId}`,
+      reason: `Credit deduction for job ${jobId}`,
+      metadata: { job_id: jobId },
+    },
+  );
 
-// After AI completion
-await trackAIUsage('cus_abc123', 500, 1200, 'gpt-4');
+  return {
+    balanceAfter: entry.balance_after,
+    overageAfter: entry.overage_after,
+  };
+}
 ```
 
-### API Rate Tracking Example
+Do not manually debit usage that is also connected to automatic meter-to-credit deduction; that charges the same consumption twice.
+
+## Read the ledger for an audit trail
+
+The SDK returns an auto-paginating iterable:
 
 ```typescript
-// Middleware to track and deduct API credits
-async function trackAPICredit(customerId: string, req: Request) {
-  await client.usageEvents.ingest({
-    events: [{
-      event_id: `api_${Date.now()}_${crypto.randomUUID()}`,
-      customer_id: customerId,
-      event_name: 'api.call',
-      timestamp: new Date().toISOString(),
-      metadata: {
-        endpoint: new URL(req.url).pathname,
-        method: req.method,
-      }
-    }]
+for await (const entry of client.creditEntitlements.balances.listLedger(
+  'cus_TV52uJWWXt2yIoBBxpjaa',
+  { credit_entitlement_id: 'cde_ztxm5XJsKxWucRWA3rjdM' },
+)) {
+  console.log({
+    id: entry.id,
+    amount: entry.amount,
+    balanceBefore: entry.balance_before,
+    balanceAfter: entry.balance_after,
+    overageBefore: entry.overage_before,
+    overageAfter: entry.overage_after,
+    createdAt: entry.created_at,
   });
 }
 ```
 
----
+Persist the Dodo ledger entry ID with internal order, support-case, or job IDs. Reconciliation should compare ledger entries and source references rather than overwrite history from a cached balance.
 
-## Next.js Integration
+## Configure automatic meter-to-credit deduction
 
-### Credit Balance API Route
+1. Attach a credit entitlement to the usage-based product.
+2. Add the meter to the same product.
+3. Enable **Bill usage in Credits** for that meter.
+4. Set `credit_entitlement_id` and `meter_units_per_credit`.
+5. Optionally set `free_threshold`; usage under it is excluded.
+6. Ingest events whose case-sensitive `event_name` matches the meter.
 
-```typescript
-// app/api/credits/balance/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import DodoPayments from 'dodopayments';
+A background worker processes new usage approximately every minute, aggregates it according to the meter, converts meter units using `meter_units_per_credit`, and consumes the oldest non-expired grants first (FIFO). Multiple meters can consume one shared credit pool at different conversion rates.
 
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-});
+This delay is material: an accepted usage event does not imply that a balance read immediately afterward includes its deduction.
 
-export async function GET(req: NextRequest) {
-  const customerId = req.nextUrl.searchParams.get('customer_id');
-  const creditId = req.nextUrl.searchParams.get('credit_id');
+Use the `usage-based-billing` skill to create the meter, choose `count`, `sum`, `max`, or `last`, define its filter, and validate event batching and metadata.
 
-  if (!customerId || !creditId) {
-    return NextResponse.json({ error: 'Missing parameters' }, { status: 400 });
-  }
+## End-to-end AI token example
 
-  try {
-    const balance = await client.creditEntitlements.balances.get(creditId, customerId);
+Assume the dashboard/API configuration already has:
 
-    return NextResponse.json({
-      available: balance.available_balance,
-      overage: balance.overage_balance,
-    });
-  } catch (error: any) {
-    return NextResponse.json({ error: error.message }, { status: 500 });
-  }
-}
-```
+- a custom-unit entitlement named `AI Token Credits`, precision `0`;
+- a subscription product that issues credits each cycle;
+- a `sum` meter whose case-sensitive event name is `ai.tokens` and key is `tokens`;
+- that meter linked through `credit_entitlement_id` and `meter_units_per_credit`;
+- a one-time product `pdt_ai_token_topup` with credits attached.
 
-### Manual Credit Grant API Route
+The following server-side script records actual model usage, reads the credit balance, and creates a top-up checkout when your verified low-balance webhook flow prompts the customer:
 
 ```typescript
-// app/api/credits/grant/route.ts
-import { NextRequest, NextResponse } from 'next/server';
 import DodoPayments from 'dodopayments';
 
 const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
+  environment: 'test_mode',
 });
 
-export async function POST(req: NextRequest) {
-  const { customerId, creditId, amount, description } = await req.json();
-
-  try {
-    const entry = await client.creditEntitlements.balances.createLedgerEntry(
-      creditId,
-      customerId,
+async function recordTokenUsage(
+  customerId: string,
+  generationId: string,
+  model: string,
+  promptTokens: number,
+  completionTokens: number,
+): Promise<number> {
+  const tokens = promptTokens + completionTokens;
+  const response = await client.usageEvents.ingest({
+    events: [
       {
-        type: 'credit',
-        amount: amount.toString(),
-        description,
-        idempotency_key: `grant_${customerId}_${Date.now()}`,
-      }
-    );
-
-    return NextResponse.json({ success: true, balance_after: entry.balance_after });
-  } catch (error: any) {
-    return NextResponse.json({ error: error.message }, { status: 500 });
-  }
-}
-```
-
-### Credit Balance Hook
-
-```typescript
-// hooks/useCreditBalance.ts
-import useSWR from 'swr';
+        event_id: `generation:${generationId}`,
+        customer_id: customerId,
+        event_name: 'ai.tokens',
+        timestamp: new Date().toISOString(),
+        metadata: {
+          tokens,
+          prompt_tokens: promptTokens,
+          completion_tokens: completionTokens,
+          model,
+        },
+      },
+    ],
+  });
 
-const fetcher = (url: string) => fetch(url).then(r => r.json());
+  return response.ingested_count;
+}
 
-export function useCreditBalance(customerId: string, creditId: string) {
-  const { data, error, mutate } = useSWR(
-    `/api/credits/balance?customer_id=${customerId}&credit_id=${creditId}`,
-    fetcher,
-    { refreshInterval: 30000 } // Refresh every 30s
+async function readTokenBalance(
+  customerId: string,
+  creditEntitlementId: string,
+): Promise<string> {
+  const response = await client.creditEntitlements.balances.retrieve(
+    customerId,
+    { credit_entitlement_id: creditEntitlementId },
   );
-
-  return {
-    available: data?.available,
-    overage: data?.overage,
-    isLoading: !error && !data,
-    isError: error,
-    refresh: mutate,
-  };
+  return response.balance;
 }
 
-// Usage in component
-function CreditDisplay() {
-  const { available, isLoading } = useCreditBalance('cus_abc123', 'cent_xxxxx');
-
-  if (isLoading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      <h3>Credits Remaining</h3>
-      <p className="text-3xl font-bold">{available}</p>
-    </div>
-  );
+async function createTopUpCheckout(customerEmail: string) {
+  return client.checkoutSessions.create({
+    product_cart: [
+      { product_id: 'pdt_ai_token_topup', quantity: 1 },
+    ],
+    customer: { email: customerEmail },
+    return_url: 'https://app.example.com/credits',
+  });
 }
-```
 
----
+async function main(): Promise<void> {
+  const customerId = 'cus_8VbC6JDZzPEqfBPUdpj0K';
+  const creditEntitlementId = 'cde_ztxm5XJsKxWucRWA3rjdM';
 
-## Common Patterns
+  const ingested = await recordTokenUsage(
+    customerId,
+    'gen_01JZAIEXAMPLE',
+    'example-model',
+    1800,
+    700,
+  );
+  console.log({ ingested });
 
-### Credit Top-Up (One-Time Purchase)
+  // Meter deduction is asynchronous; this read may still show the prior balance.
+  const balance = await readTokenBalance(customerId, creditEntitlementId);
+  console.log({ balance });
 
-Sell credit packs as one-time products:
+  // Call this after a verified credit.balance_low event and customer action.
+  const topUp = await createTopUpCheckout('customer@example.com');
+  console.log(topUp);
+}
 
-```typescript
-// Product: "500 API Credit Pack" with 500 credits attached
-const session = await client.checkoutSessions.create({
-  product_cart: [
-    { product_id: 'prod_credit_pack_500', quantity: 1 }
-  ],
-  customer: { email: 'customer@example.com' },
-  return_url: 'https://yourapp.com/credits/success',
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
 });
 ```
 
-### Subscription with Credits + Overage
+The lifecycle is:
 
-```typescript
-// Product: Pro Plan - $49/month, 10,000 tokens included, $0.002/token overage
-// Credits attached in dashboard with:
-//   - Credits per cycle: 10000
-//   - Allow overage: true
-//   - Price per unit: $0.002
-//   - Overage behavior: Bill overage at billing
+1. The model returns actual prompt and completion token counts.
+2. The app ingests one uniquely identified `ai.tokens` event.
+3. The meter aggregates the `tokens` metadata value.
+4. The worker converts units into credits and deducts FIFO from non-expired grants.
+5. Dodo emits `credit.deducted`; when configured threshold conditions are met, it emits `credit.balance_low`.
+6. The app notifies the customer and offers checkout for the attached top-up product.
 
-const session = await client.checkoutSessions.create({
-  product_cart: [
-    { product_id: 'prod_pro_with_credits', quantity: 1 }
-  ],
-  subscription_data: { trial_period_days: 14 },
-  customer: { email: 'customer@example.com' },
-  return_url: 'https://yourapp.com/success',
-});
-```
+Do not poll every minute to synthesize your own threshold event. Use the verified webhook and keep polling only for user-interface freshness.
 
-### Access Control Based on Credits
+## Handle credit webhooks
 
-```typescript
-// Middleware to check credit balance before allowing API access
-async function requireCredits(customerId: string, creditId: string): Promise<boolean> {
-  try {
-    const balance = await client.creditEntitlements.balances.get(creditId, customerId);
-    const available = parseFloat(balance.available_balance);
-    return available > 0;
-  } catch {
-    return false;
-  }
-}
+Webhook signature verification, raw-body handling, retries, and event deduplication are covered in the `webhook-integration` skill. Verify with `client.webhooks.unwrap()` before dispatching any event; never trust a parsed, unverified body.
 
-// Express middleware
-async function creditGate(req: Request, res: Response, next: Function) {
-  const customerId = req.headers['x-customer-id'] as string;
-  const hasCredits = await requireCredits(customerId, 'cent_api_credits');
+All credit events except `credit.balance_low` use the full ledger payload.
 
-  if (!hasCredits) {
-    return res.status(402).json({
-      error: 'Insufficient credits',
-      message: 'Your credit balance is exhausted. Please upgrade your plan or purchase more credits.',
-    });
-  }
+| Exact event | Application action |
+|---|---|
+| `credit.added` | Refresh cached balance; correlate the grant or purchase and ledger entry. |
+| `credit.deducted` | Refresh cached balance and usage display; reconcile the source usage/job. |
+| `credit.expired` | Refresh balance; notify only if your product policy promises expiry notices. |
+| `credit.rolled_over` | Refresh balance and expose the new rollover grant in account history. |
+| `credit.rollover_forfeited` | Refresh balance and explain forfeiture according to the configured rollover limit. |
+| `credit.overage_charged` | Reconcile the overage charge with billing and customer-visible history. |
+| `credit.overage_reset` | Clear cached overage state after confirming the ledger payload. |
+| `credit.manual_adjustment` | Reconcile the adjustment with its internal support/admin operation. |
+| `credit.balance_low` | Deduplicate, refresh the authoritative balance, notify the customer, and offer upgrade or top-up. |
 
-  next();
-}
-```
+### Low-balance payload
 
-### Promotional Credit Grants
+`credit.balance_low` has a dedicated payload:
 
-```typescript
-// Grant promotional credits with idempotency
-async function grantPromoCredits(
-  customerId: string,
-  creditId: string,
-  amount: number,
-  promoCode: string
-) {
-  await client.creditEntitlements.balances.createLedgerEntry(
-    creditId,
-    customerId,
-    {
-      type: 'credit',
-      amount: amount.toString(),
-      description: `Promotional credit: ${promoCode}`,
-      idempotency_key: `promo_${promoCode}_${customerId}`, // Prevents double-granting
-    }
-  );
+```json
+{
+  "business_id": "bus_H4ekzPSlcg",
+  "type": "credit.balance_low",
+  "timestamp": "2025-08-04T06:15:00.000000Z",
+  "data": {
+    "payload_type": "CreditBalanceLow",
+    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
+    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
+    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
+    "credit_entitlement_name": "API Credits",
+    "available_balance": "15",
+    "subscription_credits_amount": "100",
+    "threshold_percent": 20,
+    "threshold_amount": "20"
+  }
 }
 ```
 
----
+### Low-balance notification flow
 
-## Real-World Pricing Examples
+1. Verify the raw webhook and deduplicate by `webhook-id` as described in `webhook-integration`.
+2. Confirm `type === 'credit.balance_low'` and validate the dedicated payload.
+3. Map `customer_id` to the authenticated application account; do not accept a customer ID supplied by a browser.
+4. Read the current balance with `balances.retrieve(...)` because another grant or deduction may have occurred since emission.
+5. If the balance is still below your customer-notification policy, enqueue one notification keyed by webhook ID or threshold occurrence.
+6. Link to a one-time top-up checkout or plan-upgrade flow.
+7. Record notification delivery separately from the Dodo ledger; never manufacture a ledger entry for an email.
 
-### AI SaaS Platform
+## Enforce credits safely
 
-```
-Plan      | Price    | Credits/Month  | Overage
-----------|----------|----------------|----------
-Starter   | $29/mo   | 10,000 tokens  | $0.003/token
-Pro       | $99/mo   | 100,000 tokens | $0.002/token
-Enterprise| $499/mo  | 1,000,000 tokens| $0.001/token
-
-Credit Config:
-  Type: Custom Unit ("AI Tokens"), Precision: 0
-  Rollover: 25% max, 1-month timeframe
-  Overage: Bill overage at billing
-  Meter: ai.generation (Sum on tokens)
-```
-
-### API Gateway
-
-```
-Plan      | Price    | Credits/Month  | Overage
-----------|----------|----------------|----------
-Free      | $0/mo    | 1,000 calls    | Blocked
-Developer | $19/mo   | 50,000 calls   | $0.001/call
-Business  | $99/mo   | 500,000 calls  | $0.0005/call
-
-Credit Config:
-  Type: Custom Unit ("API Calls"), Precision: 0
-  Rollover: Disabled
-  Overage: Free=disabled, Dev+=forgive at reset
-  Meter: api.request (Count)
-```
-
-### Cloud Storage
+### Best-effort balance gate
 
-```
-Plan      | Price    | Credits/Month  | Overage
-----------|----------|----------------|----------
-Personal  | $9/mo    | 100 GB-hours   | $0.05/GB-hour
-Team      | $49/mo   | 1,000 GB-hours | $0.03/GB-hour
-
-Credit Config:
-  Type: Custom Unit ("GB-hours"), Precision: 2
-  Rollover: 50% max, carries over once
-  Overage: Enabled with 200% limit
-  Meter: storage.usage (Sum)
-```
+For a precision-`0` entitlement, a server can perform a coarse pre-check with integer-safe parsing:
 
----
-
-## Credit Ledger
-
-Every credit operation is recorded with full audit trail:
-
-| Transaction Type | Description |
-|-----------------|-------------|
-| **Credit Added** | Credits granted (subscription, one-time, or API) |
-| **Credit Deducted** | Credits consumed through usage or manual debit |
-| **Credit Expired** | Credits expired without rollover |
-| **Credit Rolled Over** | Credits carried forward to the next period |
-| **Rollover Forfeited** | Rolled credits forfeited after max count reached |
-| **Overage Charged** | Usage beyond credit balance with overage enabled |
-| **Auto Top-Up** | Automatic credit replenishment at low balance |
-| **Manual Adjustment** | Credit or debit applied manually by merchant |
-| **Refund** | Credits refunded |
-
-Each ledger entry records balance before/after, overage before/after, description, and reference to the source.
-
----
-
-## Best Practices
-
-### 1. Start Simple
-Begin with a single credit type and no rollover. Add complexity based on customer usage patterns.
-
-### 2. Use Meaningful Units
-Name credits after what they represent ("API Calls", "AI Tokens") not generic terms.
-
-### 3. Set Low Balance Thresholds
-Configure thresholds and subscribe to `credit.balance_low` to alert customers before they run out.
-
-### 4. Use Idempotency Keys
-Always include idempotency keys for manual ledger entries to prevent double-granting:
 ```typescript
-idempotency_key: `promo_${promoCode}_${customerId}`
-```
-
-### 5. Configure Expiry Thoughtfully
-Short expiry (7 days) drives urgency but may frustrate. 30–90 days is customer-friendly for most SaaS.
-
-### 6. Test the Full Cycle
-In test mode: create credits → attach to product → purchase → send usage events → verify deduction → test expiration and rollover.
+async function hasAtLeastWholeCredits(
+  customerId: string,
+  creditEntitlementId: string,
+  required: bigint,
+): Promise<boolean> {
+  const response = await client.creditEntitlements.balances.retrieve(
+    customerId,
+    { credit_entitlement_id: creditEntitlementId },
+  );
 
-### 7. Monitor Overage
-If using "Bill overage at billing", monitor overage amounts to avoid unexpected charges for customers.
+  return BigInt(response.balance) >= required;
+}
+```
 
----
+Use this only for precision `0`. For fractional credits, use an arbitrary-precision decimal implementation that preserves the entitlement's configured precision.
+
+This read is not a reservation. Two concurrent requests can both observe enough balance, and automatic meter deductions may not yet be reflected.
+
+### Strict request enforcement
+
+Choose one of these patterns:
+
+- **Predictable fixed cost:** create an idempotent manual debit before serving. Treat an insufficient-balance `400` as denial. If work fails after debit, issue a separately idempotent compensating credit with a linked reason. Do not also meter the same usage.
+- **Variable cost such as AI tokens:** reserve estimated capacity atomically in your own datastore, enforce per-customer concurrency, ingest actual usage afterward, and reconcile local reservations with Dodo webhooks and ledger entries.
+- **Overage product:** authorize against the product's overage policy and your own risk limit, not merely `balance > 0`.
+
+Return an application-level payment/credit-required response with a top-up or upgrade path when authorization fails. Do not expose Dodo API errors or secrets to the client.
+
+### Race conditions to avoid
+
+- **Check then act:** a remote balance read followed by work is not atomic.
+- **Immediate post-event read:** the meter worker may not have processed the event.
+- **Parallel workers:** multiple jobs can consume the same apparent balance without a local reservation or atomic debit.
+- **Retry with new IDs:** changing `event_id` or `idempotency_key` after a timeout can duplicate usage or adjustments.
+- **Cache as authority:** webhook-maintained balances are useful for display, not strict authorization.
+- **Mixed deduction paths:** automatic meter deduction plus manual debit double-counts consumption.
+
+## Common mistakes
+
+1. **Confusing two resources.** `creditEntitlements` and `entitlements` are different. Credit balances do not live under `client.entitlements.grants`.
+2. **Calling invented balance methods.** Use `balances.retrieve(customerId, { credit_entitlement_id })`, not `balances.get(creditId, customerId)`.
+3. **Using the wrong ledger argument order.** `createLedgerEntry` receives `customerId` first; `credit_entitlement_id` belongs in the request object.
+4. **Using `type` or `description` for adjustments.** Confirmed fields are `entry_type` and `reason`.
+5. **Getting the grants argument order wrong.** `creditEntitlements.balances.listGrants(customerID, params)` does exist and takes the customer id first, with the entitlement supplied in the params object. It returns a paginated page, so read `.items` rather than treating the result as an array. Use `customers.listCreditEntitlements(customerID)` when you want the customer-level summary instead.
+6. **Treating `available_balance` as the balance API field.** The confirmed balance response uses `balance` and `overage`; `available_balance` belongs to the dedicated low-balance webhook payload.
+7. **Choosing precision casually.** It supports `0–10` for custom units and cannot be changed after creation.
+8. **Using JavaScript floating point for credits.** API amounts are decimal strings. Preserve them as strings or use decimal arithmetic.
+9. **Exceeding adjustment bounds.** Ledger amounts map to `NUMERIC(38,28)`, and the integer part must be below `10^10`.
+10. **Misstating monetary units.** Currency amounts use the smallest currency unit. Do not label cents as dollars.
+11. **Using unstable idempotency keys.** A timestamp or random key on every retry defeats deduplication. Derive the key from the immutable business operation.
+12. **Retrying an insufficient debit blindly.** Manual debits can return `400` for insufficient balance; route the customer to top-up or your overage policy.
+13. **Assuming event ingestion is synchronous deduction.** Meter-to-credit processing occurs approximately every minute.
+14. **Using Dodo's balance as a per-request lock.** The docs explicitly warn against strict authorization from asynchronously reported meter balances.
+15. **Mismatching meter names.** Usage `event_name` matching is case-sensitive.
+16. **Sending duplicate IDs within one batch.** Duplicate `event_id` values in the same ingestion request reject the entire request. Previously ingested IDs are ignored on retry.
+17. **Inventing a deduplication window.** Current docs require unique event IDs but do not publish a retention duration.
+18. **Getting conversion backward.** `meter_units_per_credit` is usage units required for one credit, and is required when `credit_entitlement_id` is set.
+19. **Ignoring the free threshold.** Usage under `free_threshold` is excluded before credit deduction.
+20. **Supplying one rollover timeframe field.** `rollover_timeframe_count` and `rollover_timeframe_interval` must be supplied together.
+21. **Using the wrong rollover enum case.** Confirmed values are `Day`, `Week`, `Month`, and `Year`.
+22. **Assuming expiry happens before rollover.** Rollover is applied first; only the remainder expires.
+23. **Inventing overage enum values.** Use only `forgive_at_reset`, `invoice_at_billing`, `carry_deficit`, or `carry_deficit_auto_repay`.
+24. **Omitting overage pricing dependencies.** Enabled overage requires `price_per_unit`; a price requires `currency`.
+25. **Attaching too many credits.** The current product limit is five credit entitlements.
+26. **Assuming checkout grants arbitrary credits.** Credits must already be attached to the purchased product or add-on.
+27. **Handling only the common webhooks.** Include `credit.overage_reset` and `credit.rollover_forfeited`, not only added, deducted, and low-balance events.
+28. **Parsing an unverified webhook.** Verify the raw body with `client.webhooks.unwrap()` as covered in `webhook-integration`; never hand-roll HMAC or trust re-serialized JSON.
+29. **Inventing historical snapshot APIs.** Use ledger `balance_before` and `balance_after` for transaction-level history.
+30. **Using deprecated purchase methods.** New checkout flows use `client.checkoutSessions.create(...)`, not `payments.create(...)` or `subscriptions.create(...)`.
+31. **Using the wrong host or key format.** Valid hosts are `https://test.dodopayments.com` and `https://live.dodopayments.com`; keys start with `dodo_test_` or `dodo_live_`.
 
 ## Resources
 
 - [Credit-Based Billing Guide](https://docs.dodopayments.com/features/credit-based-billing)
-- [Credit Entitlements API](https://docs.dodopayments.com/api-reference/credit-entitlements/create-credit-entitlement)
-- [Credit Webhook Events](https://docs.dodopayments.com/developer-resources/webhooks/intents/credit)
-- [Usage-Based Billing](https://docs.dodopayments.com/features/usage-based-billing/introduction)
-- [Subscription Integration](https://docs.dodopayments.com/developer-resources/subscription-integration-guide)
+- [Create Credit Entitlement API](https://docs.dodopayments.com/api-reference/credit-entitlements/create-credit-entitlement)
+- [Get Customer Balance API](https://docs.dodopayments.com/api-reference/credit-entitlements/get-customer-balance)
+- [Create Ledger Entry API](https://docs.dodopayments.com/api-reference/credit-entitlements/create-ledger-entry)
+- [List Customer Ledger API](https://docs.dodopayments.com/api-reference/credit-entitlements/list-customer-ledger)
+- [Credit Webhook Reference](https://docs.dodopayments.com/developer-resources/webhooks/intents/credit)
+- [Meter Guide](https://docs.dodopayments.com/features/usage-based-billing/meters)
+- [Usage Event Ingestion API](https://docs.dodopayments.com/api-reference/usage-events/ingest-events)
+- [Create Product API](https://docs.dodopayments.com/api-reference/products/post-products)