--- title: Fetching Credit Memos slug: fetching-credit-memos docTags: createdAt: 2026-02-13T04:24:47.243Z --- 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: ```javascript 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 ```http 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 ```http 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) ```http 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 ```http 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 | ### 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:** ```http GET /credit-memos?includes=assets,orders ``` ## Basic Examples ### Fetch All Credit Memos with Pagination ```javascript 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 ```javascript 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 ```javascript 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 ```javascript // 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' } }); ``` ### Filtering by Multiple Criteria ```javascript // Get credit memos by payment status const response = await fetch('https://api.nue.io/credit-memos?paymentStatus=Applied', { method: 'GET', headers: { 'nue-api-key': 'YOUR_API_KEY_HERE', 'Content-Type': 'application/json' } }); ``` ## Response Structure ### Standard Response Format ```json { "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 ```json { "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 ```json { "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 ```javascript 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 ```javascript // 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 ```javascript async function getCustomerCreditMemoSummary(customerId) { const response = await fetch(`https://api.nue.io/customers/${customerId}/credit-memos?paymentStatus=Applied,PartiallyApplied&includes=assets`, { headers: { 'nue-api-key': 'YOUR_API_KEY_HERE' } }); return await response.json(); } ``` ### Financial Reconciliation: Find Unapplied Credits ```javascript async function getUnappliedCredits() { const response = await fetch('https://api.nue.io/credit-memos?status=Active&limit=200', { headers: { 'nue-api-key': 'YOUR_API_KEY_HERE' } }); return await response.json(); } ``` ### Audit Trail: Track Invoice Cancellation Credits ```javascript async function getInvoiceCancellationCredits() { const response = await fetch('https://api.nue.io/credit-memos?source=PaymentOperation', { headers: { 'nue-api-key': 'YOUR_API_KEY_HERE' } }); return await response.json(); } ``` ## Next Steps - [Credit Memo Data Reference](<./Credit Memo Data Reference.mdx>) - Complete field definitions and data types - [Credit Memos Overview](docId\:Q-UnkVDF36bmmfEgzHjQm) - Business context and lifecycle management - [Advanced Invoice Workflows](docId\:CLOXmSgZcdsgL81_HBMe5) - 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.