Customers
Customers
A customer is whoever is paying you. Merida creates one automatically the first time someone checks out, and lets you connect it back to a user record in your own system.
External customer IDs
Pass external_customer_id when you create a checkout. It's whatever your app uses to identify the user: a database ID, a tenant slug, an email hash. Merida stores it on the customer and surfaces it on every downstream object: invoices, subscriptions, webhook payloads.
curl -X POST https://api.meridapay.com/checkouts \
-H "Authorization: Bearer $MERIDA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_id": "prod_8f5f7c7e-...",
"customer_email": "[email protected]",
"external_customer_id": "user_123"
}'
When the buyer pays, you receive a payment.succeeded webhook with external_customer_id: "user_123", and you join straight to the user_123 row in your own database. No identifier mapping table needed.
Looking up by either ID
Most endpoints that read a customer accept either the Merida UUID or your external_customer_id in the URL. The service tries both, so you don't have to remember which one you have.
curl https://api.meridapay.com/customers/user_123/balances \
-H "Authorization: Bearer $MERIDA_API_KEY"
The same call works with the UUID:
curl https://api.meridapay.com/customers/3f1b...-...-.../balances \
-H "Authorization: Bearer $MERIDA_API_KEY"
Reading balances
Returns every meter the customer accrues against, with credited, consumed, rollover, and the current balance for the active billing period. Empty list if the customer is unknown (never an error), so it's safe to call from a feature gate that loads before checkout.
{
"data": [
{
"meter_id": "...",
"meter_slug": "api_calls",
"meter_name": "API calls",
"unit_label": "calls",
"period_start": "2026-05-01T00:00:00Z",
"period_end": "2026-06-01T00:00:00Z",
"credited": 10000,
"rollover": 0,
"consumed": 412,
"balance": 9588,
"is_exhausted": false
}
]
}
See Meters for how balances are accrued.
Email and metadata
customer_email is required on the first checkout. Subsequent checkouts for the same external_customer_id reuse the existing customer. To update the email on file, change it on your side and pass the new value on the next checkout.
metadata on the checkout flows through to the customer for buyer-tagging (UTM source, sign-up plan, support tier). Strings only, up to 50 keys.
Next up
Subscriptions →