Managing Customers

A customer record in ODUS represents a person or organization you charge. Each record holds contact information — name, email, phone number, and addresses. Payments, subscriptions, and saved payment methods reference the customer by its id (prefixed cus_).

Prerequisites

• A valid ODUS secret key with the customer:update permission to update customers, and customer:read to find them.

How customers are created

v2 has no endpoint for creating a customer. A customer record is created when a shopper pays through the Checkout SDK, from the details collected at checkout.

To charge a returning customer, pass their id as customer when you create a payment. To find that id, look the customer up by email.

Update a customer

Send a POST /v2/customers/{id} request with the fields you want to change. All fields are optional — only the fields you include will be updated.

{
  "name": "Jane Doe",
  "phoneNumber": "+15559876543"
}

Updating metadata

The metadata field is merged with any existing metadata on every update. Only the keys you include are changed — existing keys that you do not mention are preserved. To remove a specific key, set its value to an empty string. To clear all metadata at once, send null.

{
  "metadata": {
    "internalAccountId": "acct_9870",
    "tier": "premium"
  }
}

note

Metadata is for your own use only. ODUS does not use metadata values in any processing logic.

View a customer in the Dashboard

1. In the Dashboard, go to Customers.
2. Click a customer row to open the customer detail page.

The detail page shows:

• Subscriptions — all subscriptions linked to this customer.
• Payments — all payment attempts associated with this customer.
• Payment methods — saved cards and other payment methods stored for this customer.
• Customer details — contact information and editable metadata, displayed in the right sidebar.

To edit the customer's name, email, phone number, or address, click Edit on the customer card at the top of the page. To remove a stored phone number, clear the field and save.

To edit metadata directly in the Dashboard, use the metadata editor in the Customer details sidebar and save your changes.

Find and filter customers

Dashboard

On the Customers list page, use the filter bar to narrow results:

Filter	Description
Email	Exact or partial match on email address
Name	Exact or partial match on display name
Created Date	Filter by creation date range

Click any row to open that customer's detail page.

API

Use GET /v2/customers with query parameters to filter results. Text filters such as email and name support eq, ne, like, ilike, in and nin. id is matched whole and accepts eq, ne, in and nin.

Look a customer up by email with eq. ODUS stores email addresses in lowercase and lowercases the value you send, so the case does not matter:

GET /v2/customers?email[eq]=jane@example.com

Every other string filter is case-sensitive, and like matches the start of a value. To match any part of a value in any case, use ilike and wrap the value in % wildcards, encoded as %25:

GET /v2/customers?name[ilike]=%25smith%25&sortDirection=desc&limit=20

warning

A filter whose case does not match the stored value returns an empty page, not an error. Use ilike for names and other values people type.

The response is paged by cursor. To fetch the next page, send the returned pagination.nextCursor as cursor.

See Pagination, Filtering, and Sorting for the full list of supported filter fields and operators.

Read a customer's payment methods and subscriptions

A v2 customer object does not include the customer's payment methods or subscriptions. Read each from its own list endpoint, filtered by the customer's id:

GET /v2/payment-methods?customer[eq]=cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV
GET /v2/subscriptions?customer[eq]=cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV

Your key needs payment_method:read and subscription:read for these requests.