Customers

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

Create a customer

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" }
  }'

• 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

# 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" }'

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

Archive a customer

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

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.