Fetching Account Credit Pools

16 min

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:

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

Endpoint

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

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:

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

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)

{
  "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

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

Best Practices

Use pagination for customers with many credit pools to reduce response size

Filter by pool IDs when you only need specific pools to improve performance

Cache results appropriately since credit pool data changes infrequently

Handle empty results gracefully - customers may not have any credit pools