---
title: Fetching Account Credit Pools
slug: fetching-account-credit-pools
createdAt: 2026-02-13T04:24:47.243Z
---

This guide explains how to retrieve account credit pool data for a customer using the Nue API. Account credit pools represent a customer's credit balances within specific credit pools.

## Prerequisites

Before you begin, ensure you have:

- A valid Nue API key with read permissions
- Customer ID for the account you want to query
- Basic understanding of REST APIs and JSON

## Authentication

All requests require authentication using your Nue API key in the `nue-api-key` header:

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");
```

## Endpoint

```javascript
GET https://api.nue.io/customers/{customerId}/account-credit-pools
```

### Path Parameters

| Parameter    | Type   | Required | Description                                                   |
| ------------ | ------ | -------- | ------------------------------------------------------------- |
| `customerId` | String | Yes      | The unique identifier of the customer (UUID or Salesforce ID) |

### Query Parameters

| Parameter        | Type           | Required | Description                                                        |
| ---------------- | -------------- | -------- | ------------------------------------------------------------------ |
| `accountPoolIds` | Array\[String] | No       | JSON-encoded array of specific account credit pool IDs to retrieve |
| `page`           | Integer        | No       | Page number for pagination (default: 1, minimum: 1)                |
| `limit`          | Integer        | No       | Number of results per page (default: 100, range: 1-500)            |

## Basic Usage

### Fetch All Account Credit Pools for a Customer

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

const customerId = "001RK00001jt2i1YAA";

fetch(`https://api.nue.io/customers/${customerId}/account-credit-pools`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Found ${result.pagination.total} credit pools`);

    result.data.forEach(pool => {
      console.log(`\nPool: ${pool.name}`);
      console.log(`  ID: ${pool.id}`);
      console.log(`  Balance: ${pool.balance}`);
      console.log(`  Status: ${pool.status}`);
      console.log(`  Credit Pool: ${pool.creditPool.name}`);
      console.log(`  Committed: ${pool.creditPool.committed}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Fetch Specific Account Credit Pools

Filter by specific pool IDs:

```javascript
const customerId = "001RK00001jt2i1YAA";
const poolIds = ["474935a8-16cc-46a6-927d-74c962cf460f"];
const encodedPoolIds = encodeURIComponent(JSON.stringify(poolIds));

fetch(`https://api.nue.io/customers/${customerId}/account-credit-pools?accountPoolIds=${encodedPoolIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    result.data.forEach(pool => {
      console.log(`Pool: ${pool.name}`);
      console.log(`  Balance: ${pool.balance}`);
      console.log(`  Credit Type ID: ${pool.creditTypeId}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Paginated Retrieval

```javascript
const customerId = "001RK00001jt2i1YAA";

fetch(`https://api.nue.io/customers/${customerId}/account-credit-pools?page=1&limit=10`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Page ${result.pagination.page} of ${result.pagination.totalPages}`);
    console.log(`Showing ${result.data.length} of ${result.pagination.total} pools`);
    console.log(`Has next page: ${result.pagination.hasNext}`);

    result.data.forEach(pool => {
      console.log(`- ${pool.name}: ${pool.balance} credits`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

## Response Structure

### Success Response (200 OK)

```json
{
  "status": "SUCCESS",
  "data": [
    {
      "balance": 240000,
      "createdById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
      "createdDate": "2026-01-10T19:12:10.465Z",
      "creditPool": {
        "committed": true,
        "createdById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
        "createdDate": "2026-01-08T02:10:10.259Z",
        "creditTypeId": "6984e433-0151-4351-b9e2-b7f557672707",
        "id": "d3496002-9430-4f8d-9e67-6c6ac8793bd7",
        "isDefault": false,
        "lastModifiedById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
        "lastModifiedDate": "2026-01-08T02:10:10.259Z",
        "name": "Default Committed Credit Pool"
      },
      "creditPoolId": "d3496002-9430-4f8d-9e67-6c6ac8793bd7",
      "creditTypeId": "6984e433-0151-4351-b9e2-b7f557672707",
      "customerId": "001RK00001jt2i1YAA",
      "id": "474935a8-16cc-46a6-927d-74c962cf460f",
      "lastModifiedById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
      "lastModifiedDate": "2026-01-10T19:13:30.027Z",
      "name": "Default Committed Credit Pool",
      "status": "Active"
    }
  ],
  "warnings": [],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  }
}
```

### Response Fields

### Account Credit Pool Object

| Field              | Type   | Description                                    |
| ------------------ | ------ | ---------------------------------------------- |
| `id`               | String | Unique identifier for the account credit pool  |
| `name`             | String | Display name of the account credit pool        |
| `balance`          | Number | Current credit balance in the pool             |
| `status`           | String | Status of the pool (e.g., "Active")            |
| `customerId`       | String | ID of the customer who owns this pool          |
| `creditPoolId`     | String | ID of the associated credit pool configuration |
| `creditTypeId`     | String | ID of the credit type                          |
| `creditPool`       | Object | Nested credit pool configuration details       |
| `createdDate`      | String | ISO 8601 timestamp of creation                 |
| `createdById`      | String | ID of the user who created the pool            |
| `lastModifiedDate` | String | ISO 8601 timestamp of last modification        |
| `lastModifiedById` | String | ID of the user who last modified the pool      |

### Credit Pool Object (Nested)

| Field              | Type    | Description                             |
| ------------------ | ------- | --------------------------------------- |
| `id`               | String  | Unique identifier for the credit pool   |
| `name`             | String  | Display name of the credit pool         |
| `committed`        | Boolean | Whether credits are committed/prepaid   |
| `isDefault`        | Boolean | Whether this is the default credit pool |
| `creditTypeId`     | String  | ID of the credit type                   |
| `createdDate`      | String  | ISO 8601 timestamp of creation          |
| `lastModifiedDate` | String  | ISO 8601 timestamp of last modification |

### Pagination Object

| Field         | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| `page`        | Integer | Current page number              |
| `limit`       | Integer | Number of results per page       |
| `total`       | Integer | Total number of results          |
| `totalPages`  | Integer | Total number of pages            |
| `hasNext`     | Boolean | Whether there is a next page     |
| `hasPrevious` | Boolean | Whether there is a previous page |

## Error Handling

### Common Errors

| Error Code             | Description                    | Resolution               |
| ---------------------- | ------------------------------ | ------------------------ |
| `CUSTOMER_NOT_FOUND`   | Customer ID does not exist     | Verify the customer ID   |
| `INVALID_PARAMETER`    | Invalid query parameter format | Check parameter encoding |
| `AUTHENTICATION_ERROR` | Invalid or missing API key     | Verify your API key      |

### Error Response Example

```json
{
  "status": "FAILURE",
  "errorType": "NOT_FOUND",
  "errorCode": "CUSTOMER_NOT_FOUND",
  "message": "Customer with ID '001RK00001invalid' was not found."
}
```

## Best Practices

1. **Use pagination** for customers with many credit pools to reduce response size
2. **Filter by pool IDs** when you only need specific pools to improve performance
3. **Cache results** appropriately since credit pool data changes infrequently
4. **Handle empty results** gracefully - customers may not have any credit pools
