---
title: Fetching Credit Flows
slug: fetching-credit-flows
docTags: 
createdAt: 2026-02-13T04:24:48.354Z
---

This guide explains how to retrieve credit flow transactions for a customer using the Nue API. Credit flows represent individual credit transactions that track the movement of credits in and out of a customer's account.

## 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}/credit-flows
```

### 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 account pool IDs to filter by                 |
| `assetNumbers`   | Array\[String] | No       | JSON-encoded array of subscription asset numbers to filter by       |
| `includes`       | String         | No       | Comma-separated list of related data to include: `product`, `usage` |
| `page`           | Integer        | No       | Page number for pagination (default: 1, minimum: 1)                 |
| `limit`          | Integer        | No       | Number of results per page (default: 100, range: 1-500)             |

## Understanding the `includes` Parameter

The `includes` parameter allows you to enrich credit flow data with related information:

### `includes=product`

Enriches each credit flow with product information by looking up the associated subscription's product. The product object is added to each credit flow that has an `assetNumber`.

### `includes=usage`

Enriches credit flows with usage data. **This only applies to credit flows with **`transactionType: "Consume"`. For consume transactions, the API fetches the associated Usage record using the `transactionSourceId` and adds it as a `usage` object on the credit flow.

### `includes=product,usage`

When both are specified, usage records will also include their associated product information.

## Basic Usage

### Fetch All Credit Flows 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}/credit-flows`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Found ${result.pagination.total} credit flows`);

    result.data.forEach(flow => {
      console.log(`\nTransaction: ${flow.name}`);
      console.log(`  Type: ${flow.transactionType} (${flow.recordType})`);
      console.log(`  Amount: ${flow.transactionAmount}`);
      console.log(`  Balance After: ${flow.balance}`);
      console.log(`  Date: ${flow.transactionDate}`);
      console.log(`  Asset: ${flow.assetNumber}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Fetch Credit Flows with Product Information

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

fetch(`https://api.nue.io/customers/${customerId}/credit-flows?includes=product`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' || result.status === 'PARTIAL_SUCCESS') {
    result.data.forEach(flow => {
      console.log(`\nTransaction: ${flow.name}`);
      console.log(`  Type: ${flow.transactionType}`);
      console.log(`  Amount: ${flow.transactionAmount}`);

      if (flow.product) {
        console.log(`  Product: ${flow.product.name}`);
        console.log(`  Product SKU: ${flow.product.sku}`);
      }
    });

    // Check for warnings about unavailable product data
    if (result.warnings.length > 0) {
      console.log('\nWarnings:', result.warnings);
    }
  }
})
.catch(error => console.log('Error:', error));
```

### Fetch Credit Flows with Usage Data

Use this when you need to see the underlying usage records for consumption transactions:

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

fetch(`https://api.nue.io/customers/${customerId}/credit-flows?includes=usage`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' || result.status === 'PARTIAL_SUCCESS') {
    result.data.forEach(flow => {
      console.log(`\nTransaction: ${flow.name}`);
      console.log(`  Type: ${flow.transactionType}`);
      console.log(`  Amount: ${flow.transactionAmount}`);

      // Usage data is only available for 'Consume' transaction types
      if (flow.transactionType === 'Consume' && flow.usage) {
        console.log(`  Usage ID: ${flow.usage.id}`);
        console.log(`  Usage Quantity: ${flow.usage.quantity}`);
        console.log(`  Usage Date: ${flow.usage.usageDate}`);
      }
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Fetch Credit Flows with Both Product and Usage Data

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

fetch(`https://api.nue.io/customers/${customerId}/credit-flows?includes=product,usage`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' || result.status === 'PARTIAL_SUCCESS') {
    result.data.forEach(flow => {
      console.log(`\nTransaction: ${flow.name} - ${flow.transactionType}`);

      if (flow.product) {
        console.log(`  Product: ${flow.product.name}`);
      }

      // Usage data includes product when both includes are specified
      if (flow.usage) {
        console.log(`  Usage Quantity: ${flow.usage.quantity}`);
        if (flow.usage.product) {
          console.log(`  Usage Product: ${flow.usage.product.name}`);
        }
      }
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Filter by Account 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}/credit-flows?accountPoolIds=${encodedPoolIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Found ${result.pagination.total} credit flows for specified pools`);
    result.data.forEach(flow => {
      console.log(`- ${flow.name}: ${flow.transactionType} ${flow.transactionAmount}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Filter by Asset Numbers (Subscription Names)

```javascript
const customerId = "001RK00001jt2i1YAA";
const assetNumbers = ["SUB-000185", "SUB-000005"];
const encodedAssetNumbers = encodeURIComponent(JSON.stringify(assetNumbers));

fetch(`https://api.nue.io/customers/${customerId}/credit-flows?assetNumbers=${encodedAssetNumbers}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Found ${result.pagination.total} credit flows for specified subscriptions`);
  }
})
.catch(error => console.log('Error:', error));
```

### Combined Filtering

Filter by both account pools and asset numbers (AND logic):

```javascript
const customerId = "001RK00001jt2i1YAA";
const poolIds = ["474935a8-16cc-46a6-927d-74c962cf460f"];
const assetNumbers = ["SUB-000185"];

const params = new URLSearchParams({
  accountPoolIds: JSON.stringify(poolIds),
  assetNumbers: JSON.stringify(assetNumbers),
  page: '1',
  limit: '50'
});

fetch(`https://api.nue.io/customers/${customerId}/credit-flows?${params}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  console.log(`Found ${result.pagination.total} matching credit flows`);
})
.catch(error => console.log('Error:', error));
```

## Response Structure

### Success Response (200 OK)

```json
{
  "status": "SUCCESS",
  "data": [
    {
      "accountPoolId": "474935a8-16cc-46a6-927d-74c962cf460f",
      "assetNumber": "SUB-000185",
      "balance": 120000,
      "createdById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
      "createdDate": "2026-01-10T19:13:30.03Z",
      "creditEndDate": "2027-01-09",
      "creditId": "44b04d30-b8a2-4c95-ab70-d89a1bd594e1",
      "creditNumber": "CRE-000000000014",
      "creditStartDate": "2026-01-10",
      "creditTypeId": "6984e433-0151-4351-b9e2-b7f557672707",
      "currencyIsoCode": "USD",
      "customerId": "001RK00001jt2i1YAA",
      "id": "faa09e3e-f746-4743-a650-42a916f36ad2",
      "lastModifiedById": "ddd60c9f-e694-4760-b832-f720ebf22a53",
      "lastModifiedDate": "2026-01-10T19:13:30.03Z",
      "name": "CF-000000000015",
      "recordType": "Inflow",
      "salesAccountId": "001RK00001jt2i1YAA",
      "transactionAmount": 120000,
      "transactionDate": "2026-01-10",
      "transactionSource": "OrderProduct",
      "transactionSourceId": "802RK00000v2qUjYAI",
      "transactionType": "Issue"
    }
  ],
  "warnings": [],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  }
}
```

### Response Fields

### Credit Flow Object

| Field                 | Type   | Description                                                               |
| --------------------- | ------ | ------------------------------------------------------------------------- |
| `id`                  | String | Unique identifier for the credit flow                                     |
| `name`                | String | Credit flow name (e.g., "CF-000000000015")                                |
| `accountPoolId`       | String | ID of the associated account credit pool                                  |
| `assetNumber`         | String | Subscription name/number associated with this flow                        |
| `balance`             | Number | Credit balance after this transaction                                     |
| `transactionAmount`   | Number | Amount of credits in this transaction                                     |
| `transactionDate`     | String | Date of the transaction (YYYY-MM-DD)                                      |
| `transactionType`     | String | Type of transaction: `Issue`, `Consume`, `Expire`, `Cancel`, `CreditBack` |
| `transactionSource`   | String | Source of the transaction (e.g., "OrderProduct", "Usage")                 |
| `transactionSourceId` | String | ID of the source record                                                   |
| `recordType`          | String | Direction of flow: `Inflow` or `Outflow`                                  |
| `creditId`            | String | ID of the associated credit record                                        |
| `creditNumber`        | String | Credit record number                                                      |
| `creditStartDate`     | String | Start date of the credit validity period                                  |
| `creditEndDate`       | String | End date of the credit validity period                                    |
| `creditTypeId`        | String | ID of the credit type                                                     |
| `currencyIsoCode`     | String | Currency code (e.g., "USD")                                               |
| `customerId`          | String | ID of the customer                                                        |
| `salesAccountId`      | String | ID of the sales account                                                   |
| `product`             | Object | Product details (when `includes=product`)                                 |
| `usage`               | Object | Usage details (when `includes=usage`, only for Consume transactions)      |

### Transaction Types

| Type         | Description                         | Record Type |
| ------------ | ----------------------------------- | ----------- |
| `Issue`      | Credits granted to the customer     | Inflow      |
| `Consume`    | Credits used by the customer        | Outflow     |
| `Expire`     | Credits that have expired           | Outflow     |
| `Cancel`     | Credits that were canceled          | Outflow     |
| `CreditBack` | Credits returned to the customer    | Inflow      |
| `CashOut`    | Credits cashed out to credit memos  | Outflow     |
| `Reissue`    | Credits reissued to the customer    | Inflow      |
| `Rollover`   | Credits rolled over to a new period | Outflow     |

### Partial Success Response

When enrichment (product or usage) partially fails:

```json
{
  "status": "PARTIAL_SUCCESS",
  "data": [...],
  "warnings": [
    {
      "code": "PRODUCTS_UNAVAILABLE",
      "message": "Product data unavailable for some credit flows"
    }
  ],
  "pagination": {...}
}
```

## 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      |

## Best Practices

1. **Use pagination** for customers with many transactions
2. **Filter by date range** using `accountPoolIds` or `assetNumbers` for better performance
3. **Request enrichment selectively** - only use `includes` when you need the additional data
4. **Handle PARTIAL\_SUCCESS** gracefully - check the warnings array for enrichment failures
5. **Cache product data** separately if you need it frequently