Skip to main content
skill CX Codex

customer-management — Claude Code skill: Dodo Payments customer lifecycle

customer-management is a Claude Code skill for managing Dodo Payments customers: create records, set up portals and payment methods, manage wallets, and link app users to billing IDs.

MIT 202 installs ★ 14 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dodopayments/skills --skill customer-management -a claude-code
Open on GitHub

What customer-management does

Covers the full customer lifecycle: record CRUD, self-service portal for invoices and subscriptions, saved card management, and wallet operations in USD or INR. Each customer gets an ID prefixed cus_ and groups payments and portal access. The portal is a hosted session valid for 24 hours; customers visit the link to view invoices, cancel subscriptions, change plans, update cards, and download license keys.

Wallets hold real money (USD, INR) for future purchases—separate from usage credits, which have their own credit-based-billing skill. Wallet ledger entries guard against duplicates via idempotency_key: if a network call fails after creating an entry, retrying with the same key returns the existing entry instead of charging twice.

Entitlements represent feature or file grants. Call listCreditEntitlements to read credit balances, listEntitlements for feature grants, and listEntitlementGrants for individual grants and revocation status. Requires the DODO_PAYMENTS_API_KEY environment variable.

What it helps with

  • Link an app user to a customer ID in the billing system
  • Give customers access to a hosted portal for self-service billing
  • Grant or revoke feature access based on subscription state
  • Credit a wallet balance for refunds or promotional rewards
  • List and delete saved payment methods for a customer

Example prompts for the agent

  • Create a customer with email [email protected] and metadata userId: user_12345
  • Open the subscription management portal for customer cus_abc123
  • Credit $50 to the wallet for customer cus_abc123 with reason: Refund for order #12345

How to install customer-management

1Skills CLI (Vercel)

npx skills add dodopayments/skills --skill customer-management -a claude-code

2Manually: put the files in place

~/.claude/skills/customer-management/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/customer-management/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about customer-management

How do I install customer-management in Claude Code?

Run npx skills add dodopayments/skills --skill customer-management -a claude-code in your terminal, then open ~/.claude/skills/customer-management/SKILL.md in Claude Code.

What does this skill do?

It manages the customer lifecycle in Dodo Payments: create and update records, host a self-service billing portal, manage saved payment methods, handle wallet balances and transactions, and check feature entitlements and credit grants.

What's the difference between a wallet and usage credits?

Wallets store real money (USD, INR) that customers spend on purchases. Usage credits are counters for API consumption or service usage; use the credit-based-billing skill for those.

Source text

SKILL.md · MIT
---
name: customer-management
description: Dodo Payments customer management, covering customer CRUD, saved payment methods, real-money customer wallets and ledger entries, entitlements, and hosted customer portal sessions. Use when linking app users to cus_ IDs, opening a Manage billing portal, listing or deleting payment methods, or crediting wallets; use credit-based-billing for usage credits.
---

# 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.

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

## Customer Portal

Create a time-bound session that redirects customers to a hosted portal. In the portal, customers can view invoices, cancel subscriptions, change plans, update payment methods, recover on-hold subscriptions, and download license keys.

Never call the SDK from the browser: it uses your secret API key. Create the session in a server route and return only the link.

```typescript
// Server route: create a portal session
const session = await client.customers.customerPortal.create('cus_abc123', {
  return_url: 'https://yourapp.com/dashboard',
  // send_email: true, // optionally also email the link to the customer
});

return Response.json({ link: session.link });
```

```typescript
// Browser: redirect the customer
const res = await fetch('/api/portal', { method: 'POST' });
const { link } = await res.json();
window.location.href = link;
```

The portal session link is valid for 24 hours. Pass `send_email: true` to have Dodo also email the link to the customer. Customers cannot:
- Create new subscriptions (use checkout for that)
- Refund themselves
- Change their email or name (contact support)
- Access billing history beyond invoices

If you need to rebuild any of these, you're duplicating the portal. Use it instead.

## Saved Payment Methods

List and delete payment methods saved to a customer.

```typescript
// List payment methods for a customer
const methods = await client.customers.retrievePaymentMethods('cus_abc123');
console.log(methods);
// {
//   items: [{ payment_method_id: 'pm_xyz789', payment_method: 'card' }]
// }

// Delete a payment method
await client.customers.deletePaymentMethod('pm_xyz789', {
  customer_id: 'cus_abc123',
});
```

Payment methods are created during checkout when the customer opts to save their card. You cannot create them directly via the API.

## Customer Wallets

Wallets hold real-money balances (USD, INR) that customers can spend on future purchases. They are distinct from usage credits. List wallet balances and create idempotent ledger entries.

```typescript
// List wallets for a customer
const wallets = await client.customers.wallets.list('cus_abc123');
console.log(wallets);
// {
//   items: [
//     { currency: 'USD', balance: 5000, customer_id: 'cus_abc123', ... },
//     { currency: 'INR', balance: 100000, customer_id: 'cus_abc123', ... }
//   ],
//   total_balance_usd: 17000
// }

// List ledger entries
const entries = await client.customers.wallets.ledgerEntries.list('cus_abc123', {
  page_size: 20,
});

// Create a ledger entry (credit or debit)
// Amounts are in the smallest currency unit (cents for USD, paise for INR)
await client.customers.wallets.ledgerEntries.create('cus_abc123', {
  amount: 1000, // $10.00 in USD
  currency: 'USD',
  entry_type: 'credit', // or 'debit'
  reason: 'Refund for order #12345',
  idempotency_key: 'refund_order_12345_v1',
});
```

**Idempotency is critical.** If your network fails after creating a ledger entry, retrying with the same `idempotency_key` returns the existing entry instead of creating a duplicate charge. Always use a stable, unique key per transaction.

Wallets are real money. Do not create entries without idempotency keys, and do not expose wallet balances to the client without verification.

## Reading Customer Entitlements

Entitlements are feature or file grants. There are three methods:

```typescript
// List credit entitlements (credit balances)
const credits = await client.customers.listCreditEntitlements('cus_abc123');
console.log(credits);
// {
//   items: [{
//     credit_entitlement_id: 'cred_ent_1',
//     balance: '5000',
//     name: 'API Calls',
//     overage: '0',
//     unit: 'calls'
//   }]
// }

// List feature/file entitlements
const features = await client.customers.listEntitlements('cus_abc123');
console.log(features);
// {
//   items: [
//     {
//       grant_id: 'entg_feature_1',
//       entitlement_id: 'ent_feature_1',
//       entitlement_name: 'Pro Features',
//       integration_type: 'feature_flag',
//       status: 'delivered',
//       created_at: '2026-01-01T00:00:00Z',
//       updated_at: '2026-01-01T00:00:00Z'
//     }
//   ]
// }

// List individual grants (with revocation status)
const grants = await client.customers.listEntitlementGrants('cus_abc123', {
  page_size: 50,
});
console.log(grants);
// {
//   items: [{
//     id: 'entg_feature_1',
//     entitlement_id: 'ent_feature_1',
//     status: 'Delivered',
//     revoked_at: null
//   }]
// }
```

## Linking Your App's Users to Dodo Customers

Store the Dodo customer ID in your user record, or use metadata to link them.

```typescript
// Option 1: Store the Dodo customer ID in your database
const customer = await client.customers.create({
  email: user.email,
  name: user.name,
});
await db.users.update(user.id, { dodo_customer_id: customer.customer_id });

// Option 2: Use metadata to store your user ID
const customer = await client.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    app_user_id: user.id,
  },
});

// Later, retrieve by email (not a direct API call, but common pattern)
// You must store the mapping yourself or query Dodo's list endpoint
const customers = await client.customers.list({ page_size: 100 });
const found = customers.items.find(c => c.email === user.email);
```

**Email matching pitfall:** if a user changes their email in your app, the Dodo customer email won't update automatically. Always sync email changes explicitly via `client.customers.update()`.

## Common mistakes

**Creating duplicate customers per checkout.** Passing `customer: { email }` does not create a new customer each time: by default, checkout uses the email to find an existing customer and attaches the session to it. Duplicates come from setting `feature_flags.always_create_new_customer: true`, or from calling `customers.create` before every checkout. Create the customer once (or let the first checkout create it), store its `customer_id`, and pass that on later checkouts.

```typescript
// WRONG: forces a new customer record on every checkout
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { email: user.email },
  feature_flags: { always_create_new_customer: true },
});

// RIGHT: reuse the stored customer ID, or fall back to email (matched to an existing customer by default)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: user.dodo_customer_id
    ? { customer_id: user.dodo_customer_id }
    : { email: user.email },
});
```

**Building a bespoke billing UI instead of using the portal.** The portal handles invoices, cancellations, plan changes, payment method updates, and on-hold recovery. If you rebuild these, you're duplicating work and missing edge cases.

**Mutating wallet balances without an idempotency key.** Retries will create duplicate entries and charge the customer twice.

```typescript
// WRONG
await client.customers.wallets.ledgerEntries.create('cus_abc123', {
  amount: 1000,
  currency: 'USD',
  entry_type: 'credit',
  reason: 'Refund',
  // No idempotency_key
});

// RIGHT
await client.customers.wallets.ledgerEntries.create('cus_abc123', {
  amount: 1000,
  currency: 'USD',
  entry_type: 'credit',
  reason: 'Refund',
  idempotency_key: 'refund_order_12345_v1',
});
```

**Exposing portal links publicly.** Portal sessions are time-bound and tied to a customer ID. Don't log them or share them in URLs; generate them server-side and redirect immediately.

**Confusing wallets with credits.** Wallets hold real money (USD, INR). Credits are usage-based entitlements. See the `credit-based-billing` skill for credit management.

## Resources

- [Customer Management](https://docs.dodopayments.com/features/customers)
- [Customer Portal](https://docs.dodopayments.com/features/customer-portal)
- [Customer Wallets](https://docs.dodopayments.com/features/customer-wallet)
- [Customers API Reference](https://docs.dodopayments.com/api-reference/customers)

© dodopayments · MIT · dodopayments/skills

Similar skills

All skills for Backend and APIs →
signals-scout-customer-analytics-billing-and-usage PostHog signals-scout-customer-analytics-billing-and-usage — a skill for Claude Code that tracks product usage and forecast MRR changes within individual accounts. It spots product-level shifts hidden by a steady account total. CX Codex +1 149installs aws-billing-and-cost-management aws aws-billing-and-cost-management analyzes AWS spending, discovers savings opportunities, and sets up budgets. Helps evaluate Savings Plans, detect cost anomalies, and right-size infrastructure. CX Codex +1 10,300installs subscription-management claude-office-skills subscription-management handles SaaS subscription lifecycle work, from billing and plan changes to churn prevention. Use it when designing subscription flows and revenue rules. CX Codex +1 5,200installs azure-cost-management MicrosoftDocs azure-cost-management — a skill for Claude Code and Cursor that guides Azure billing API integration, budget alerts, and cost exports. Resolves billing discrepancies and reservation issues. CX Codex +1 222installs windsurf-license-management Jeremy Longshore windsurf-license-management keeps track of Windsurf seats: builds a license inventory, sets who gets a seat, and turns usage into cost and audit reports. CX Codex +1 1installs AWS Billing and Cost Management awslabs AWS Billing and Cost Management — an MCP server that lets your coding agent read AWS billing data: costs, budgets, anomalies, commitment discounts and invoices. CX Codex +1 ★ 9,939repo stars

From the same set17

The whole set →
testing-and-go-live testing-and-go-live runs a Dodo Payments integration through test mode: cards, declines, renewals, webhooks. Then takes it to production with a launch checklist. CX Codex +1 219installs framework-adapters framework-adapters mounts official Dodo Payments adapters across Next.js, Express, Hono, Nuxt, and more. Sets up checkout, customer portal, and webhook handlers. CX Codex +1 209installs refunds-and-disputes refunds-and-disputes teaches coding agents how to issue refunds and handle dispute lifecycles with Dodo Payments. Helps wire webhooks, issue partial line-item refunds, and manage access. CX Codex +1 208installs product-catalog-management product-catalog-management manages Dodo Payments products, subscription pricing models, add-ons, and image uploads. Designed for TypeScript SDK integrations. CX Codex +1 208installs discounts-and-promotions discounts-and-promotions is a Claude Code skill for configuring Dodo Payments promo codes, checking eligibility rules, and troubleshooting codes rejected at checkout. CX Codex +1 199installs localized-pricing localized-pricing guides multi-currency setups in Dodo Payments across fixed regional prices, live Adaptive Currency conversion, and purchasing power parity (PPP) tiers. CX Codex +1 198installs mobile-checkout mobile-checkout guides integration of Dodo Payments hosted checkout into React Native, Flutter, iOS, and Android using system browsers. CX Codex +1 192installs better-auth-integration The better-auth-integration skill connects Better Auth with Dodo Payments for customer sync, checkout, portal access, usage events, and signed webhooks. CX Codex +1 192installs

Project sponsors

Companies that keep this analytics open