Skip to content
EntitlerDocs

Customers

A customer is one of your users or accounts, named by your own ID and kept in one environment.

A customer is whoever holds a plan in your product: a user, a team or a company account. You name each customer by your own ID, its external ID, so you never store an Entitler ID beside your own.

External IDs

An external ID is 1 to 120 characters of letters, digits and _, ., :, @ and -, such as ada, user_8412 or org:acme. Use an ID that never changes for the customer: their email address can change, their account ID can't. me is kept for customer tokens, so it can't be an external ID.

Each customer also has an Entitler ID, an opaque string that answers carry as customerId. You never need to store it or parse it.

Environments

A customer lives in one environment of one project. The same external ID in your test and live environments names two different customers, each with their own plans, grants and usage. A key for your test environment never sees a live customer.

Registering customers

Register a customer when they sign up or sign in, with PUT /v1/customers/{external_id}. A customer that exists already is answered as it is, so you can register on every sign-in without checking first. Registering with a name or email updates them when your key holds customers:write.

curl -X PUT "$ENTITLER_API/v1/customers/ada" \
  -H "Authorization: Bearer $ENTITLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada Lovelace", "email": "ada@example.com"}'

A new customer starts on your default plan, when you have one. Reporting usage and changing plans can register the customer in the same call: send "register": true.

Removing customers

  • DELETE /v1/customers/{external_id} deletes the customer. Registering the same external ID again creates a new customer, with none of the old one's plans or usage.
  • POST /v1/customers/{external_id}:erase erases the customer's personal details, their external ID, name, email and attributes, from every customer that ever held the external ID in the environment, deleted ones included. Use it when someone asks you to remove their data.

Edit this page on GitHub