Updating Customer

21 min

This guide walks you through updating existing Customer records using the Nue Lifecycle Management API. Learn how to modify customer information, update billing configurations, and implement efficient customer management workflows.

Prerequisites

Before you begin, ensure you have:

A valid Nue API key with customer update permissions

Valid customer ID (either Salesforce ID or Nue UUID)

Understanding of customer data structures

Basic knowledge of REST APIs and JSON

Authentication

All customer update 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");

Basic Customer Updates

Update Basic Information

Try it now: Update Customer →

const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

// Update basic customer information
const customerId = "d2e04653-ae90-49df-a986-134cf64f6d03";
const updateData = {
  name: "Acme Corporation Ltd", // Updated company name
  email: "[email protected]", // New billing email
  phone: "+1-555-0199", // Updated phone number
  description: "Leading provider of innovative business solutions"
};

fetch(`https://api.nue.io/customers/${customerId}`, {
  method: 'PATCH',
  headers: myHeaders,
  body: JSON.stringify(updateData)
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    const customer = result.data[0];
    console.log('Customer updated successfully:', result);
    console.log(`Updated: ${customer.name}`);
    console.log(`Email: ${customer.email}`);
    console.log(`Phone: ${customer.phone}`);
    console.log(`Last Modified: ${customer.lastModifiedDate}`);
    
    // Handle any warnings
    if (result.warnings && result.warnings.length > 0) {
      console.warn('Warnings:', result.warnings);
    }
  } else {
    console.error('Update failed:', result);
  }
})
.catch(error => console.log('Error updating customer:', error));

Update Business Information

Modify business-specific details for enterprise customers:

const businessUpdateData = {
  // Business details
  legalEntityName: "Acme Corporation Limited LLC",
  industry: "Financial Services", // Changed from Technology
  annualRevenue: 15000000, // Updated revenue
  numberOfEmployees: 150, // Grown from 100
  companySize: "101-250 employees",
  ownership: "Public", // Changed from Private
  funding: "IPO",
  
  // Contact updates
  timezone: "America/Chicago", // Relocated headquarters
  fax: "+1-555-0200"
};

const customerId = "d2e04653-ae90-49df-a986-134cf64f6d03";

fetch(`https://api.nue.io/customers/${customerId}`, {
  method: 'PATCH',
  headers: myHeaders,
  body: JSON.stringify(businessUpdateData)
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    const customer = result.data[0];
    console.log('✅ Business information updated:');
    console.log(`Company: ${customer.name} (${customer.legalEntityName})`);
    console.log(`Industry: ${customer.industry}`);
    console.log(`Revenue: $${customer.annualRevenue?.toLocaleString()}`);
    console.log(`Employees: ${customer.numberOfEmployees}`);
    console.log(`Ownership: ${customer.ownership}`);
  console.log(`Timezone: ${customer.timezone}`);
})
.catch(error => console.log('Error:', error));

Billing Configuration Updates

Update Payment and Billing Settings

Modify billing cycle, payment methods, and related configurations:

const billingUpdateData = {
  // Billing cycle changes
  billCycleDay: 15, // Changed from 1st to 15th
  billCycleStartMonth: "07", // Start new cycle in July
  
  // Payment configuration
  paymentMethod: "ACH", // Changed from Credit Card
  paymentTerm: "Net 15", // Faster payment terms
  autoRenew: "Yes", // Enable auto-renewal
  billingProrationEnabled: "No", // Disable proration
  
  // Tax configuration
  taxExempt: "exempt", // Customer became tax exempt
  entityId: "TAX-EXEMPT-001",
  entityUseCode: "NON-PROFIT"
};

const customerId = "d2e04653-ae90-49df-a986-134cf64f6d03";

fetch(`https://api.nue.io/customers/${customerId}`, {
  method: 'PATCH',
  headers: myHeaders,
  body: JSON.stringify(billingUpdateData)
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    const customer = result.data[0];
    console.log('💳 Billing configuration updated:');
    console.log(`Bill Cycle: Day ${customer.billCycleDay} starting ${customer.billCycleStartMonth}`);
    console.log(`Payment Method: ${customer.paymentMethod}`);
    console.log(`Payment Terms: ${customer.paymentTerm}`);
    console.log(`Auto Renew: ${customer.autoRenew}`);
    console.log(`Tax Status: ${customer.taxExempt}`);
    console.log(`Proration: ${customer.billingProrationEnabled ? 'Enabled' : 'Disabled'}`);
  }
})
.catch(error => console.log('Error:', error));

Update Address Information

Modify billing and shipping addresses:

const addressUpdateData = {
  // Updated billing address
  billingStreet: "456 New Business Plaza, Suite 200",
  billingCity: "New York",
  billingState: "NY",
  billingPostalCode: "10001",
  billingCountry: "United States",
  
  // Updated shipping address
  shippingStreet: "789 Distribution Center Way",
  shippingCity: "Newark",
  shippingState: "NJ",
  shippingPostalCode: "07102",
  shippingCountry: "United States"
};

const customerId = "d2e04653-ae90-49df-a986-134cf64f6d03";

fetch(`https://api.nue.io/customers/${customerId}`, {
  method: 'PATCH',
  headers: myHeaders,
  body: JSON.stringify(addressUpdateData)
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    const customer = result.data[0];
    console.log('📍 Address information updated:');
    console.log('\nBilling Address:');
    console.log(`   ${customer.billingStreet}`);
    console.log(`   ${customer.billingCity}, ${customer.billingState} ${customer.billingPostalCode}`);
    console.log(`   ${customer.billingCountry}`);
    
    console.log('\nShipping Address:');
    console.log(`   ${customer.shippingStreet}`);
    console.log(`   ${customer.shippingCity}, ${customer.shippingState} ${customer.shippingPostalCode}`);
  console.log(`   ${customer.shippingCountry}`);
})
.catch(error => console.log('Error:', error));

Advanced Update Patterns

Customer Lifecycle Management

Handle customer status changes and lifecycle events:

class CustomerLifecycleManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.headers = new Headers();
    this.headers.append("nue-api-key", apiKey);
    this.headers.append("Content-Type", "application/json");
  }
  
  async upgradeToEnterprise(customerId, upgradeData) {
    try {
      console.log(`🚀 Upgrading customer ${customerId} to enterprise...`);
      
      // Prepare enterprise upgrade data
      const enterpriseConfig = {
        // Business growth indicators
        annualRevenue: upgradeData.newRevenue,
        numberOfEmployees: upgradeData.newEmployeeCount,
        companySize: this.calculateCompanySize(upgradeData.newEmployeeCount),
        
        // Enhanced billing configuration
        paymentTerm: "Net 15", // Better terms for enterprise
        billingProrationEnabled: "Yes", // More flexible billing
        autoRenew: "Yes", // Ensure continuity
        
        // Account management
        description: `Enterprise customer - upgraded on ${new Date().toISOString().split('T')[0]}`,
        accountSource: "Enterprise Upgrade"
      };
      
      const response = await fetch(`https://api.nue.io/customers/${customerId}`, {
        method: 'PATCH',
        headers: this.headers,
        body: JSON.stringify(enterpriseConfig)
      });
      
      if (!response.ok) {
        throw new Error(`Upgrade failed: ${response.status} ${response.statusText}`);
      }
      
      const result = await response.json();
      
      if (result.status !== 'SUCCESS') {
        throw new Error(`Upgrade failed: ${result.error?.message || 'Unknown error'}`);
      }
      
      const updatedCustomer = result.data[0];
      
      // Log upgrade completion
      console.log('✅ Enterprise upgrade completed:');
      console.log(`   Customer: ${updatedCustomer.name}`);
      console.log(`   New Revenue: $${updatedCustomer.annualRevenue?.toLocaleString()}`);
      console.log(`   Employees: ${updatedCustomer.numberOfEmployees}`);
      console.log(`   Company Size: ${updatedCustomer.companySize}`);
      
      // Handle any warnings
      if (result.warnings && result.warnings.length > 0) {
        console.warn('Warnings:', result.warnings);
      }
      
      // Trigger additional enterprise setup
      await this.setupEnterpriseFeatures(updatedCustomer);
      
      return updatedCustomer;
      
    } catch (error) {
      console.error('❌ Enterprise upgrade failed:', error);
      throw error;
    }
  }
  
  async changePaymentMethod(customerId, newPaymentMethod, additionalConfig = {}) {
    try {
      console.log(`💳 Updating payment method for customer ${customerId}...`);
      
      const paymentUpdate = {
        paymentMethod: newPaymentMethod,
        ...additionalConfig
      };
      
      // Adjust payment terms based on method
      if (newPaymentMethod === "ACH") {
        paymentUpdate.paymentTerm = "Net 15"; // Faster for ACH
      } else if (newPaymentMethod === "Wire Transfer") {
        paymentUpdate.paymentTerm = "Net 7"; // Even faster for wire
      }
      
      const response = await fetch(`https://api.nue.io/customers/${customerId}`, {
        method: 'PATCH',
        headers: this.headers,
        body: JSON.stringify(paymentUpdate)
      });
      
      if (!response.ok) {
        throw new Error(`Payment method update failed: ${response.status}`);
      }
      
      const result = await response.json();
      
      if (result.status !== 'SUCCESS') {
        throw new Error(`Payment method update failed: ${result.error?.message || 'Unknown error'}`);
      }
      
      const customer = result.data[0];
      
      console.log('✅ Payment method updated:');
      console.log(`   Method: ${customer.paymentMethod}`);
      console.log(`   Terms: ${customer.paymentTerm}`);
      
      return customer;
      
    } catch (error) {
      console.error('❌ Payment method update failed:', error);
      throw error;
    }
  }
  
  async relocateCustomer(customerId, newAddress, newTimezone) {
    try {
      console.log(`📍 Relocating customer ${customerId}...`);
      
      const relocationData = {
        billingStreet: newAddress.street,
        billingCity: newAddress.city,
        billingState: newAddress.state,
        billingPostalCode: newAddress.postalCode,
        billingCountry: newAddress.country,
        timezone: newTimezone,
        
        // Update description to track relocation
        description: `Customer relocated to ${newAddress.city}, ${newAddress.state} on ${new Date().toISOString().split('T')[0]}`
      };
      
      const response = await fetch(`https://api.nue.io/customers/${customerId}`, {
        method: 'PATCH',
        headers: this.headers,
        body: JSON.stringify(relocationData)
      });
      
      if (!response.ok) {
        throw new Error(`Relocation failed: ${response.status}`);
      }
      
      const result = await response.json();
      
      if (result.status !== 'SUCCESS') {
        throw new Error(`Relocation failed: ${result.error?.message || 'Unknown error'}`);
      }
      
      const customer = result.data[0];
      
      console.log('✅ Customer relocation completed:');
      console.log(`   New Location: ${customer.billingCity}, ${customer.billingState}`);
      console.log(`   Timezone: ${customer.timezone}`);
      
      return customer;
      
    } catch (error) {
      console.error('❌ Customer relocation failed:', error);
      throw error;
    }
  }
  
  calculateCompanySize(employees) {
    if (employees <= 10) return "1-10 employees";
    if (employees <= 50) return "11-50 employees";
    if (employees <= 100) return "51-100 employees";
    if (employees <= 250) return "101-250 employees";
    if (employees <= 500) return "251-500 employees";
    if (employees <= 1000) return "501-1000 employees";
    return "1000+ employees";
  }
  
  async setupEnterpriseFeatures(customer) {
    // Mock enterprise feature setup
    console.log(`🔧 Setting up enterprise features for ${customer.name}...`);
    
    // In real implementation, this would:
    // - Enable advanced billing features
    // - Set up dedicated account management
    // - Configure enterprise integrations
    // - Update service level agreements
    
    console.log('✅ Enterprise features configured');
  }
}

// Usage examples
const lifecycleManager = new CustomerLifecycleManager("YOUR_API_KEY_HERE");

// Upgrade to enterprise
lifecycleManager.upgradeToEnterprise(
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  {
    newRevenue: 25000000,
    newEmployeeCount: 300
  }
).then(customer => {
  console.log('Enterprise upgrade completed');
});

// Change payment method
lifecycleManager.changePaymentMethod(
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  "ACH",
  { billingProrationEnabled: "Yes" }
).then(customer => {
  console.log('Payment method updated');
});

// Relocate customer
lifecycleManager.relocateCustomer(
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  {
    street: "100 Tech Park Drive",
    city: "Austin",
    state: "TX",
    postalCode: "73301",
    country: "United States"
  },
  "America/Chicago"
).then(customer => {
  console.log('Customer relocation completed');
});

Bulk Customer Updates

Efficiently update multiple customers with similar changes:

class BulkCustomerUpdater {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.headers = new Headers();
    this.headers.append("nue-api-key", apiKey);
    this.headers.append("Content-Type", "application/json");
  }
  
  async updateMultipleCustomers(customerUpdates, options = {}) {
    const results = {
      successful: [],
      failed: [],
      total: customerUpdates.length
    };
    
    console.log(`📝 Starting bulk update of ${customerUpdates.length} customers...`);
    
    // Process updates with controlled concurrency
    const concurrency = options.concurrency || 5;
    
    for (let i = 0; i < customerUpdates.length; i += concurrency) {
      const batch = customerUpdates.slice(i, i + concurrency);
      
      const batchPromises = batch.map(update => 
        this.updateSingleCustomer(update.customerId, update.data)
          .then(customer => ({ customerId: update.customerId, customer, success: true }))
          .catch(error => ({ customerId: update.customerId, error: error.message, success: false }))
      );
      
      const batchResults = await Promise.all(batchPromises);
      
      batchResults.forEach(result => {
        if (result.success) {
          results.successful.push(result);
          console.log(`✅ Updated: ${result.customer.name}`);
        } else {
          results.failed.push(result);
          console.log(`❌ Failed: ${result.customerId} - ${result.error}`);
        }
      });
      
      // Add delay between batches to respect rate limits
      if (i + concurrency < customerUpdates.length) {
        await this.delay(1000); // 1 second delay
      }
    }
    
    console.log(`\n📊 Bulk update completed:`);
    console.log(`   Successful: ${results.successful.length}`);
    console.log(`   Failed: ${results.failed.length}`);
    console.log(`   Total: ${results.total}`);
    
    return results;
  }
  
  async updateSingleCustomer(customerId, updateData) {
    const response = await fetch(`https://api.nue.io/customers/${customerId}`, {
      method: 'PATCH',
      headers: this.headers,
      body: JSON.stringify(updateData)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const result = await response.json();
    
    if (result.status !== 'SUCCESS') {
      throw new Error(`Update failed: ${result.error?.message || 'Unknown error'}`);
    }
    
    return result.data[0];
  }
  
  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage example - Update payment terms for multiple customers
const bulkUpdater = new BulkCustomerUpdater("YOUR_API_KEY_HERE");

const customerUpdates = [
  {
    customerId: "customer-1-id",
    data: { paymentTerm: "Net 15", autoRenew: "Yes" }
  },
  {
    customerId: "customer-2-id", 
    data: { paymentTerm: "Net 15", autoRenew: "Yes" }
  },
  {
    customerId: "customer-3-id",
    data: { paymentTerm: "Net 15", autoRenew: "Yes" }
  }
];

bulkUpdater.updateMultipleCustomers(customerUpdates, { concurrency: 3 })
  .then(results => {
    console.log('Bulk update process completed');
    
    if (results.failed.length > 0) {
      console.log('Failed updates need attention:', results.failed);
    }
  });

Error Handling and Validation

Robust Update Implementation

async function safeCustomerUpdate(customerId, updateData, options = {}) {
  const myHeaders = new Headers();
  myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
  myHeaders.append("Content-Type", "application/json");
  
  try {
    // Validate customer ID
    if (!customerId || typeof customerId !== 'string') {
      throw new Error('Valid customer ID is required');
    }
    
    // Validate update data
    if (!updateData || typeof updateData !== 'object') {
      throw new Error('Update data is required and must be an object');
    }
    
    // Remove read-only fields if present
    const sanitizedData = { ...updateData };
    delete sanitizedData.id;
    delete sanitizedData.accountNumber;
    delete sanitizedData.createdDate;
    delete sanitizedData.createdById;
    delete sanitizedData.lastModifiedDate;
    delete sanitizedData.lastModifiedById;
    
    // Validate specific fields
    if (sanitizedData.billCycleDay && (sanitizedData.billCycleDay < 1 || sanitizedData.billCycleDay > 31)) {
      throw new Error('billCycleDay must be between 1 and 31');
    }
    
    if (sanitizedData.email && !isValidEmail(sanitizedData.email)) {
      throw new Error('Invalid email format');
    }
    
    // Perform update
    const response = await fetch(`https://api.nue.io/customers/${customerId}`, {
      method: 'PATCH',
      headers: myHeaders,
      body: JSON.stringify(sanitizedData)
    });
    
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Update failed: ${response.status} ${errorText}`);
    }
    
    const result = await response.json();
    
    if (result.status !== 'SUCCESS') {
      throw new Error(`Update failed: ${result.error?.message || 'Unknown error'}`);
    }
    
    const updatedCustomer = result.data[0];
    
    // Log successful update
    if (options.verbose) {
      console.log(`✅ Customer ${updatedCustomer.name} updated successfully`);
      console.log(`   Last Modified: ${updatedCustomer.lastModifiedDate}`);
    }
    
    // Handle any warnings
    if (result.warnings && result.warnings.length > 0 && options.verbose) {
      console.warn('Warnings:', result.warnings);
    }
    
    return {
      success: true,
      customer: updatedCustomer,
      customerId: customerId
    };
    
  } catch (error) {
    console.error(`❌ Failed to update customer ${customerId}:`, error.message);
    
    return {
      success: false,
      error: error.message,
      customerId: customerId
    };
  }
}

function isValidEmail(email) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

// Usage with error handling
safeCustomerUpdate(
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  {
    email: "[email protected]",
    paymentTerm: "Net 15",
    billCycleDay: 15
  },
  { verbose: true }
).then(result => {
  if (result.success) {
    console.log('Update completed:', result.customer.name);
  } else {
    console.log('Update failed, implement retry or escalation logic');
  }
});

Updatable Fields Reference

Core Information

name - Customer name

legalEntityName - Legal entity name

email - Primary email address

phone - Primary phone number

fax - Fax number

timezone - Customer timezone

description - Customer description

Business Information

industry - Industry classification

annualRevenue - Annual revenue amount

numberOfEmployees - Employee count

companySize - Company size category

ownership - Ownership type

funding - Funding information

Billing Configuration

billCycleDay - Day of month for billing (1-31)

billCycleStartMonth - Starting month (01-12)

autoRenew - Auto-renewal setting

paymentMethod - Primary payment method

paymentTerm - Payment terms

billingProrationEnabled - Proration setting

taxExempt - Tax exemption status

entityId - Entity identifier

entityUseCode - Entity use code

Address Information

Billing: billingStreet, billingCity, billingState, billingPostalCode, billingCountry

Shipping: shippingStreet, shippingCity, shippingState, shippingPostalCode, shippingCountry

Relationships

parentCustomerId - Parent customer reference

orderPrimaryContactId - Primary contact for orders

Common Update Scenarios

Change Business Growth

// Company growth update
const growthUpdate = {
  annualRevenue: 50000000,
  numberOfEmployees: 500,
  companySize: "501-1000 employees"
};

Payment Method Migration

// Switch from credit card to ACH
const paymentMigration = {
  paymentMethod: "ACH",
  paymentTerm: "Net 15"
};

Address Relocation

// Office relocation
const relocation = {
  billingStreet: "New Address",
  billingCity: "New City",
  billingState: "NY",
  timezone: "America/New_York"
};

Best Practices

Update Strategy

Validate data before sending updates

Use partial updates - only send changed fields

Implement retry logic for transient failures

Log all updates for audit trails

Handle concurrent updates appropriately

Monitor integration warnings for enterprise customers

Performance

Batch related updates when possible

Respect rate limits (contact Nue support to confirm your limits or request an increase)

Use controlled concurrency for bulk operations

Implement proper error handling and recovery

Cache customer data to minimize API calls

Security

Validate all input data before API calls

Use HTTPS for all requests

Store API keys securely (environment variables)

Implement proper authentication checks

Log security-related errors for monitoring

Data Integrity

Validate business rules before updates

Maintain data consistency across related records

Handle dependent data appropriately

Implement proper versioning for audit trails

This comprehensive guide enables you to efficiently update customer information using the Nue Lifecycle Management API, supporting everything from simple field updates to complex lifecycle management workflows.