Customers

Customers represent your end-users. Create customer records to track payments, link wallets, and manage subscriptions across your apps.

Create a customer

POST/customers

Request body

Parameter	Type	Required	Description
`appId`	`string`	Yes	Your app UUID
`email`	`string`	No	Customer email (max 255)
`name`	`string`	No	Customer name (max 255)
`externalId`	`string`	No	Your system's user ID (max 255)
`address`	`string`	No	Street address (max 500)
`city`	`string`	No	City (max 255)
`state`	`string`	No	State/Province (max 255)
`country`	`string`	No	Country (max 255)
`postalCode`	`string`	No	Postal/zip code (max 50)
`metadata`	`object`	No	Arbitrary key-value metadata

SDK exampletypescript

const customer = await noderails.customers.create({
  email: 'alice@example.com',
  name: 'Alice Johnson',
  metadata: { plan: 'pro' },
});

console.log(customer.id); // "cust_abc123"

cURLbash

curl -X POST https://api.noderails.com/customers \
  -H "x-api-key: nr_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "email": "alice@example.com",
    "name": "Alice Johnson"
  }'

List customers

GET/customers

Query parameters

Parameter	Type	Description
`appId`	`string`	Filter by app UUID
`search`	`string`	Search by name or email (max 255)
`page`	`number`	Page number (default: 1)
`pageSize`	`number`	Items per page (max 100)

SDK exampletypescript

const result = await noderails.customers.list({
  search: 'alice',
  page: 1,
  pageSize: 25,
});

for (const customer of result.data) {
  console.log(customer.name, customer.email);
}

Retrieve a customer

GET/customers/:id

SDK exampletypescript

const customer = await noderails.customers.retrieve('cust_abc123');
console.log(customer.email);   // "alice@example.com"
console.log(customer.wallets); // [{ chainId: 1, address: "0x..." }]

Update a customer

PUT/customers/:id

Updates customer fields. Only the provided fields are changed. Omitted fields are left unchanged.

SDK exampletypescript

const updated = await noderails.customers.update('cust_abc123', {
  name: 'Alice J.',
  metadata: { plan: 'enterprise' },
});

Add a wallet

POST/customers/:id/wallets

Links a blockchain wallet address to a customer.

Parameter	Type	Required	Description
`chainId`	`number`	Yes	Blockchain chain ID (e.g. 1 for Ethereum)
`walletAddress`	`string`	Yes	Wallet address (0x-prefixed, 40 hex chars)

SDK exampletypescript

await noderails.customers.addWallet('cust_abc123', {
  chainId: 1,
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
});

Remove a wallet

DELETE/customers/:customerId/wallets/:walletId

Unlinks a wallet from a customer. Returns 204 No Content.

SDK exampletypescript

await noderails.customers.removeWallet('cust_abc123', 'wallet_xyz');

Response object

All responses are wrapped in { "success": true, "data": ... }. List endpoints add pagination.

Customer object (create / update)json

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "appId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "externalId": "user_42",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postalCode": "94105",
    "metadata": { "plan": "pro" },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "wallets": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "customerAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "chainId": 1,
        "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "hasActiveAuthorization": false,
        "authorizationType": null,
        "authorizationTxHash": null,
        "authorizedAt": null,
        "createdAt": "2025-01-15T10:30:00.000Z",
        "updatedAt": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

CustomerAccount fields

idstringUnique customer UUID

appIdstringApp this customer belongs to

externalIdstring | nullYour system's user ID

emailstring | nullCustomer email

namestring | nullCustomer name

addressstring | nullStreet address

citystring | nullCity

statestring | nullState or province

countrystring | nullCountry

postalCodestring | nullPostal or zip code

metadataobjectArbitrary key-value pairs

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last-update timestamp

walletsCustomerWallet[]Linked blockchain wallets

CustomerWallet fields

idstringWallet UUID

customerAccountIdstringParent customer UUID

chainIdnumberBlockchain chain ID (e.g. 1 for Ethereum)

walletAddressstringOn-chain wallet address

hasActiveAuthorizationbooleanWhether this wallet has an active spending authorization

authorizationTypestring | nullPERMIT or APPROVAL

authorizationTxHashstring | nullAuthorization transaction hash

authorizedAtstring | nullISO 8601 authorization timestamp

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last-update timestamp

💡

Endpoint variations

Create/update include wallets. Retrieve is richest: includes app, wallets (with chain info), the last 50 paymentIntents (selected fields), and last 50 invoices (selected fields). List includes wallets plus _count aggregates for paymentIntents, subscriptions, and invoices. Add wallet returns the wallet with chain info. Remove wallet returns 204 No Content.