Fetching Credit Memos

this guide provides comprehensive instructions for retrieving credit memo data using the nue api learn how to fetch credit memos using multiple endpoint patterns, implement filtering and pagination, and include related data for complete financial records prerequisites before you begin, ensure you have a valid nue api key with credit memo read permissions customer ids and/or credit memo ids (either internal ids or external ids) basic understanding of rest apis and json familiarity with credit memo data structures authentication all credit memo retrieval operations 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"); understanding credit memo types credit memos in nue are created in two primary ways 1\ invoice cancellation generated automatically when canceling an invoice source paymentoperation or creditconversion applied by object references the original invoice maintains complete audit trail to original invoice 2\ standalone credit memos created independently for returns, adjustments, or goodwill credits source standalone or billing no dependency on existing invoices used for product returns, billing corrections, or promotional credits endpoint patterns the nue api provides four endpoint patterns for maximum flexibility 1\ global credit memo listing get https //api nue io/credit memos retrieves credit memos across all customers supports pagination, filtering, and includes ideal for administrative dashboards and reporting 2\ customer scoped credit memos get https //api nue io/customers/{customerid}/credit memos returns credit memos for a specific customer customer id can be internal id or external id perfect for customer specific views 3\ individual credit memo (global) get https //api nue io/credit memos/{creditmemoid} fetches a single credit memo by id from any customer useful for direct credit memo access returns consistent array format 4\ customer individual credit memo get https //api nue io/customers/{customerid}/credit memos/{creditmemoid} retrieves specific credit memo for specific customer validates credit memo belongs to the customer enhanced security and data isolation query parameters pagination parameters parameter type description default limits page integer page number (1 based) 1 minimum 1 limit integer records per page 100 min 1, max 500 filtering parameters parameter type description valid values paymentstatus string filter by payment status nottransferred , transferred , transfererror , applied , partiallyapplied , paid , partialpaid , refunded , partialrefunded , writtenoff , partiallywrittenoff , canceled , creditback status string filter by credit memo status draft , active , canceled , pendingactivation , e invoicing source string filter by creation source billing , creditconversion , paymentoperation , standalone , generatefromtransaction customerid string filter by customer id any valid customer id predicate string logical operator for multiple filters and (default), or dynamic field filtering any field from the creditmemo metadata can be used as a query parameter for precise filtering , except for the following reserved fields reserved fields (cannot be used for dynamic filtering) customerids use the dedicated customerids parameter customerid use the dedicated customerid parameter includes use the dedicated includes parameter paymentstatus use the dedicated paymentstatus parameter page use for pagination only limit use for pagination only predicate use for logical operators only dynamic filtering examples get /credit memos?amount>=1000\&creditmemodate>=2024 01 01& predicate=and commonly used dynamic fields amount filter by credit memo amount ( amount>=1000 , amount<5000 ) balance filter by remaining balance ( balance>0 , balance<=100 ) creditmemodate filter by credit memo date ( creditmemodate>=2024 01 01 ) activatedtime filter by activation date ( activatedtime>=2024 01 01t00 00 00z ) appliedbyobject filter by source object type ( appliedbyobject=invoice ) taxamount filter by tax amount ( taxamount>0 ) amountwithouttax filter by pre tax amount status filter by status (but prefer the dedicated status parameter) source filter by source (but prefer the dedicated source parameter) includes parameter enrich credit memo data with related information value description related data assets include related assets assets, entitlements, subscriptions with product details orders include related orders complete order information and relationships usage get /credit memos?includes=assets,orders basic examples fetch all credit memos with pagination const response = await fetch('https //api nue io/credit memos?page=1\&limit=25', { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); const creditmemos = await response json(); console log(`found ${creditmemos pagination total} credit memos`); console log(`page ${creditmemos pagination page} of ${creditmemos pagination totalpages}`); fetch customer credit memos const customerid = "001ks00000dvz1ayad"; const response = await fetch(`https //api nue io/customers/${customerid}/credit memos`, { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); const customercreditmemos = await response json(); fetch single credit memo with related data const creditmemoid = "5622f52c c234 4981 8ea3 aa58dc578604"; const response = await fetch(`https //api nue io/credit memos/${creditmemoid}?includes=assets,orders`, { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); const creditmemowithdetails = await response json(); advanced filtering examples filter by payment status // get all applied credit memos const response = await fetch('https //api nue io/credit memos?paymentstatus=applied\&limit=50', { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); filter by source and date range // get standalone credit memos from last 30 days const thirtydaysago = new date(); thirtydaysago setdate(thirtydaysago getdate() 30); const datefilter = thirtydaysago toisostring() split('t')\[0]; const response = await fetch(`https //api nue io/credit memos?source=standalone\&creditmemodate>=${datefilter}`, { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); complex filtering with or logic // get credit memos that are either applied or have balance > 100 const response = await fetch('https //api nue io/credit memos?paymentstatus=applied\&balance>=100& predicate=or', { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); filter invoice cancellation credit memos // get credit memos created from invoice cancellations const response = await fetch('https //api nue io/credit memos?appliedbyobject=invoice\&source=paymentoperation', { method 'get', headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); response structure standard response format { "status" "success", "data" \[ { "id" "5622f52c c234 4981 8ea3 aa58dc578604", "name" "cm 00000123", "customerid" "001ks00000dvz1ayad", "amount" 1500 00, "balance" 750 00, "amountwithouttax" 1363 64, "taxamount" 136 36, "status" "active", "paymentstatus" "partiallyapplied", "source" "standalone", "creditmemodate" "2024 03 15", "duedate" "2024 04 14", "startdate" "2024 03 01", "enddate" "2024 03 31", "createddate" "2024 03 15t10 30 00z", "activatedtime" "2024 03 15t11 00 00z", "appliedbyobject" null, "appliedbyid" null, "comments" "goodwill credit for service disruption", "creditmemopdf" "https //nue io/pdfs/credit memos/cm 00000123 pdf" } ], "warnings" \[], "pagination" { "page" 1, "limit" 25, "total" 150, "totalpages" 6, "hasnext" true, "hasprevious" false } } response with asset details { "status" "success", "data" \[ { "id" "5622f52c c234 4981 8ea3 aa58dc578604", "name" "cm 00000123", "amount" 1500 00, "balance" 750 00, "assets" \[ { "assetnumber" "a 001234", "assettype" "subscription", "productname" "premium software license", "startdate" "2024 01 01", "enddate" "2024 12 31", "status" "active" } ], "orders" \[ { "id" "ord abc123", "name" "ord 001234", "status" "activated", "activateddate" "2024 01 15" } ] } ], "pagination" { "page" 1, "limit" 25, "total" 1, "totalpages" 1, "hasnext" false, "hasprevious" false } } error handling common error responses { "status" "failure", "errortype" "invalid parameter", "errorcode" "invalid payment status format", "message" "invalid payment status provided invalidstatus valid options are nottransferred, transferred, applied, partiallyapplied, refunded, partialrefunded, writtenoff, partiallywrittenoff, canceled, creditback" } validation errors error code description resolution invalid payment status format invalid payment status value use valid payment status values invalid includes format invalid includes parameter use assets , orders , or comma separated combination invalid predicate parameter invalid predicate value use and or or graphql syntax error invalid filter parameters check field names and values api key invalid invalid or missing api key verify api key in nue api key header rate limiting credit memo endpoints are subject to rate limiting read operations 10 requests per second 429 status returned when rate limit exceeded retry strategy implement exponential backoff best practices 1\ use appropriate endpoint pattern global listings administrative dashboards customer scoped customer portals and account views individual access direct credit memo operations customer individual secure, validated access 2\ implement efficient pagination async function fetchallcreditmemos() { let allcreditmemos = \[]; let page = 1; let hasmore = true; while (hasmore) { const response = await fetch(`https //api nue io/credit memos?page=${page}\&limit=100`, { headers { 'nue api key' 'your api key here' } }); const result = await response json(); allcreditmemos push( result data); hasmore = result pagination hasnext; page++; } return allcreditmemos; } 3\ optimize related data loading use includes parameter only when needed assets for financial reconciliation and asset tracking orders for order to cash process analysis 4\ handle backwards compatibility legacy customerids parameter still supported new rest patterns recommended for cleaner code both patterns return identical data structures performance considerations filtering performance server side filtering payment status, status, source client side filtering complex field combinations recommended use server side filters first, then client side refinement large dataset handling // efficient large dataset processing async function processlargecreditmemodataset(processor) { let page = 1; let hasmore = true; while (hasmore) { const response = await fetch(`https //api nue io/credit memos?page=${page}\&limit=500`, { headers { 'nue api key' 'your api key here' } }); const result = await response json(); // process batch await processor(result data); hasmore = result pagination hasnext; page++; // rate limiting courtesy await new promise(resolve => settimeout(resolve, 100)); } } use case examples customer portal display customer credit memos async function getcustomercreditmemosummary(customerid) { const response = await fetch(`https //api nue io/customers/${customerid}/credit memos?paymentstatus=applied,partiallyapplied& predicate=or\&includes=assets`, { headers { 'nue api key' 'your api key here' } }); return await response json(); } financial reconciliation find unapplied credits async function getunappliedcredits() { const response = await fetch('https //api nue io/credit memos?balance>0\&status=active\&limit=200', { headers { 'nue api key' 'your api key here' } }); return await response json(); } audit trail track invoice cancellation credits async function getinvoicecancellationcredits(startdate, enddate) { const response = await fetch(`https //api nue io/credit memos?appliedbyobject=invoice\&source=paymentoperation\&creditmemodate>=${startdate}\&creditmemodate<=${enddate}`, { headers { 'nue api key' 'your api key here' } }); return await response json(); } next steps credit memo data reference docid\ tbatbkhg7ysjlopwwi7x0 complete field definitions and data types credit memos overview docid\ ze9peaclcuoiaypmiofeq business context and lifecycle management process payment docid\ srcsfv4mtx6qymclkkjp9 credit memo application to invoices the credit memo api provides comprehensive access to both invoice cancellation and standalone credit memos with flexible filtering, pagination, and data enrichment capabilities for complete financial management