Fetching Credit Flows

22 min

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:

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}/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

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

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:

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

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

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)

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):

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)

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

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

Use pagination for customers with many transactions

Filter by date range using accountPoolIds or assetNumbers for better performance

Request enrichment selectively - only use includes when you need the additional data

Handle PARTIAL_SUCCESS gracefully - check the warnings array for enrichment failures

Cache product data separately if you need it frequently