Skip to main content

What a Customer Carries

Customers represent the people or companies who pay you. Each customer can carry multiple subscriptions, a card on file, prepaid wallets, entitlements, DPDP consent records, and a churn score.

Create a Customer

The billing address is flat (line1, city, state, zip, country), not a nested object. state and zip matter: they drive CGST/SGST-vs-IGST for India and the sales-tax lookup for US buyers.

B2B Customers (India)

For business customers in India, capture the GSTIN and tax profile for proper invoicing:
string
15-character Indian GST identification number. When present, invoices show the buyer’s legal name and registration, and B2B e-invoicing rules apply.
string
business or consumer — drives B2B vs B2C invoice treatment.
string
Indian state code (e.g. 29 for Karnataka) — decides CGST/SGST vs IGST.
See the GST Invoicing guide for how these fields flow onto the tax invoice.

List and Search Customers

The customer API surface is deliberately small: create, list, and the card-on-file update below. There is no general update or delete endpoint today — identity changes and deletion are dashboard/support operations, and payment details change through the portal flows.

Card on File

PUT /v1/customers/{id}/payment-method updates the card display metadata Recurso shows on the customer and dunning surfaces:
The actual payment instrument lives at the gateway. Customers change it themselves through the Customer Portal — Stripe SetupIntent or a fresh UPI mandate — or through your checkout. When a payment fails on an expired card, send a magic link so they can fix it in one click.

Customer Portal

The portal is customer-facing and passwordless — customers request a magic link by email; no API key or session management on your side:
The emailed link opens a 7-day portal session where customers view and pay invoices, update payment methods, download PDFs, and cancel subscriptions. See the Customer Portal guide.

Churn Score

Recurso scores every customer’s churn risk from real billing signals (payment failures, dunning history, subscription age):
score is 0–100; risk_level is low / medium / high / critical. See Churn Prediction for high-risk lists and alerts.

What Hangs Off a Customer

Wallets

GET /v1/customers/{id}/wallets — prepaid balances that settle invoices before any gateway.

Entitlements

GET /v1/customers/{id}/entitlements — the feature grants resolved across their active subscriptions.

Consents (DPDP)

GET /v1/customers/{id}/consents — recorded consent trail for Indian data-protection compliance.

Churn

GET /v1/customers/{id}/churn — the score above, plus tenant-wide high-risk lists.