> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomobile.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> Check balances and view credit transaction history

Endpoints for viewing and managing organization credits.

***

<Info>
  **Base path: `/credits`**
</Info>

These endpoints are accessible by any authenticated user for their own organization.

### Types

<Accordion title="Type Definitions">
  ```typescript theme={null}
  interface GetBalanceResponseDto {
    balance: number;
  }

  interface GetTransactionsQueryDto {
    page?: number; // default: 1
    limit?: number; // default: 20, max: 100
    startDate?: string; // ISO date string
    endDate?: string; // ISO date string
  }

  interface CreditTransaction {
    id: string;
    organizationId: string;
    type: 'credit_add' | 'call_charge' | 'sms_charge' | 'adjustment' | 'initial';
    amount: number; // Positive for add, negative for charge
    balanceAfter: number;
    callId: string | null;       // Reference to call for call_charge transactions
    smsProgramId: string | null; // Reference to SMS program for sms_charge transactions
    description: string | null;
    createdBy: string | null;
    createdAt: string;
  }

  interface GetTransactionsResponseDto {
    data: CreditTransaction[];
    meta: PaginationMeta;
  }

  // Shared pagination meta (from @lib/shared/pagination)
  interface PaginationMeta {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }
  ```
</Accordion>

### Get credit balance

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/credits/balance \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "balance": 150.00
}
```

### Get credit transaction history

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/credits/transactions?page=1&limit=10 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "tx-001",
      "organizationId": "org-123",
      "type": "credit_add",
      "amount": 100,
      "balanceAfter": 150,
      "callId": null,
      "description": "Monthly credit allocation",
      "createdBy": "user-123",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}
```

***

## Credit Behavior

### Cost Calculation

Credits are deducted per node execution during calls:

| Node Type                                | Billing                           | Cost              |
| ---------------------------------------- | --------------------------------- | ----------------- |
| DIAL                                     | Per second (no rounding, min 10s) | 0.075 credits/sec |
| PLAY                                     | Free                              | 0                 |
| RECORD                                   | Per second (ceil)                 | 0.057 credits/sec |
| COLLECT\_AUDIO                           | Per second (ceil)                 | 0.057 credits/sec |
| SAY (TTS)                                | Per second (ceil)                 | 0.047 credits/sec |
| SMS                                      | Per message                       | 1.887 credits     |
| DTMF                                     | Free                              | 0                 |
| ANSWER, HANGUP, CONDITION, SET\_VARIABLE | Free                              | 0                 |

**SMS Program Billing:**

SMS programs (bulk campaigns) are billed at the same rate as SMS nodes:

* 1.887 credits per message
* Billed at campaign completion
* Transaction type: `sms_charge`
* Allows negative balance (send first, pay later)

**Other services (future):**

| Service  | Billing          | Cost              |
| -------- | ---------------- | ----------------- |
| STT      | Per second       | 0.047 credits/sec |
| AI Agent | Per second       | 0.057 credits/sec |
| WhatsApp | Per conversation | 8.113 credits     |

**Notes:**

* Unanswered calls (DIAL with no connection) are not charged
* DIAL has minimum billing of 10 seconds (if answered)
* Ongoing calls can push balance negative
* Credits are deducted after call completion

### Out of Credits Behavior

When an organization's balance reaches zero or below:

1. **Running programs** are paused with status `paused_no_credits`
2. **Queued calls** are cancelled
3. **Ongoing calls** are allowed to complete (balance may go negative)
4. **New call requests** are rejected with `InsufficientCreditsError`

To resume operations:

1. Credits are added to the organization
2. Programs must be manually resumed via program management API