customer-management

Customer Management

Build customer records, hosted self-service portals, saved payment methods, and real-money wallet ledgers. This skill covers the full customer lifecycle: CRUD operations, payment method management, time-bound portal sessions, and idempotent wallet transactions.

When to use this skill

• Creating, listing, retrieving, or updating customer records
• Building a self-service customer portal for invoices, subscriptions, and payment methods
• Managing saved payment methods and customer payment history
• Implementing customer wallet balances and ledger entries for credits or refunds
• Linking your app's user records to Dodo customers
• Reading customer entitlements and credit balances

Core concepts

Customers are records in Dodo that group payments, subscriptions, and portal access. Each customer has an ID (prefix cus_), email, name, and optional metadata.

Customer Portal is a hosted, time-bound session that lets customers self-serve: view invoices, cancel subscriptions, change plans, update payment methods, recover on-hold subscriptions, and download license keys. You create a session and redirect to its link.

Payment Methods are saved cards or other payment instruments linked to a customer. You can list and delete them; creation happens during checkout.

Customer Wallets hold real-money balances (USD, INR) that customers can spend on future purchases. They are NOT the same as usage credits (see credit-based-billing skill). Wallet ledger entries are idempotent via idempotency_key to prevent duplicate charges.

Entitlements are feature or file grants. listCreditEntitlements returns credit balances; listEntitlements returns feature/file grants; listEntitlementGrants lists individual grants with revocation status.

Customer CRUD

Create, list, retrieve, and update customer records.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

// Create a customer
const customer = await client.customers.create({
  email: '[email protected]',
  name: 'Alice Chen',
  metadata: {
    userId: 'user_12345',
    tier: 'premium',
  },
});
console.log(customer.customer_id); // cus_...

// List customers
const customers = await client.customers.list({
  page_size: 10,
});

// Retrieve a customer
const retrieved = await client.customers.retrieve('cus_abc123');

// Update a customer
await client.customers.update('cus_abc123', {
  name: 'Alice Chen-Smith',
  metadata: { tier: 'enterprise' },
});