Customers

A customer (cus_…) represents who you bill. Each customer owns one wallet and can hold multiple subscriptions.

Create a customer

cURL

curl -s "$TRILE_API/v1/customers" \
  -H "x-api-key: $TRILE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "asha@example.com",
    "name": "Asha K.",
    "phone": "+9779800000000",
    "metadata": { "internal_user_id": "42" }
  }'

TypeScript

import { Configuration, CustomersApi } from '@trilehq/sdk'

const customers = new CustomersApi(new Configuration({ apiKey: process.env.TRILE_KEY }))

const { data: customer } = await customers.createCustomer({
  createCustomer: {
    email: 'asha@example.com',
    name: 'Asha K.',
    phone: '+9779800000000',
    metadata: { internal_user_id: '42' },
  },
  idempotencyKey: crypto.randomUUID(),
})
// customer.id → "cus_…"

• email is required and unique per business — a duplicate returns 409 customer_already_exists.
• phone should be E.164 (+977…). The customer uses it for wallet OTP auth.
• metadata is up to 50 string key/value pairs you control; Trile stores and returns them untouched. Use it to link a Trile customer to your own user record.

Retrieve, list, update

cURL

# Retrieve
curl "$TRILE_API/v1/customers/cus_01ARZ3..." -H "x-api-key: $TRILE_KEY"

# List (cursor paginated) with a search and status filter
curl "$TRILE_API/v1/customers?search=asha&status=active&limit=50" -H "x-api-key: $TRILE_KEY"

# Update (PATCH — Idempotency-Key required)
curl -X PATCH "$TRILE_API/v1/customers/cus_01ARZ3..." \
  -H "x-api-key: $TRILE_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Asha Karki" }'

TypeScript

// Retrieve
const { data: customer } = await customers.getCustomer({ customerId: 'cus_01ARZ3...' })

// List (cursor paginated) with a search and status filter
const { data: page } = await customers.listCustomers({
  search: 'asha',
  status: 'active',
  limit: '50',
})
// page.items, page.nextCursor

// Update
const { data: updated } = await customers.updateCustomer({
  customerId: 'cus_01ARZ3...',
  updateCustomer: { name: 'Asha Karki' },
  idempotencyKey: crypto.randomUUID(),
})

List supports search, status (active/archived), date-range filters, and cursor pagination.

Archive a customer

cURL

curl -X DELETE "$TRILE_API/v1/customers/cus_01ARZ3..." -H "x-api-key: $TRILE_KEY"

TypeScript

const { data } = await customers.archiveCustomer({ customerId: 'cus_01ARZ3...' })
// data → { archived: true, customerId: "cus_…" }

This is a soft delete (sets archivedAt) — it returns { "archived": true, "customerId": "cus_…" }. Existing subscriptions and the wallet are not destroyed; archiving just hides the customer from default lists.

Next

Give a customer something to buy: Products & prices.