Fetching Credit Memos

34 min

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

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();

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'
  }
});

Filtering by Multiple Criteria

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

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

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&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?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() {
  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 - Complete field definitions and data types

Credit Memos OverviewCredit Memos Overview - Business context and lifecycle management

Advanced Invoice WorkflowsAdvanced Invoice Workflows - 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.