Fetching Credit Flows

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