> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kintra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Who a customer is in Kintra's model, how a Kintra customer maps onto a user you already have, and what a customer record carries.

A customer is one person who holds XP, tier standing and redemption history under your tenant. You create the record, Kintra issues it an id, and every other customer route takes that id. A customer is the membership behind a person you already have in your own product: you keep the account, Kintra keeps what that person has earned with you. {/* trace: A-03, A-04, P-03 */}

## Mapping a customer onto your own users

Kintra does not store your user id, and no create body has a field for one. The mapping runs the other way: you create a customer, keep the `id` Kintra returns, and store it on your own user record. {/* trace: P-03 */}

Creating a customer needs an email address and nothing else. First and last name are optional, as is a country, club membership and any attributes you have defined. The response carries the created customer, including its `id`, `username`, `status` and `onboarding_status`. {/* trace: P-04 */}

The address is what makes a second create fail rather than duplicate. An email already registered under your tenant returns 409, so if you are importing an existing user base you can either check the customer list for the address first or treat the 409 as "already imported" and move on. The same address under another tenant is another customer, and is not a conflict. What you should not do is rely on re-creating a customer to look one up: keep the id. {/* trace: P-05 */}

Call it once per person, at signup or during an import. Like every write on this surface it requires an idempotency key, which is what makes a retry after a timeout safe rather than duplicating the person. [Request conventions](/conventions) has the full rules. {/* trace: CreateCustomer */}

## What a customer record carries

The parts you will use in a first integration: {/* trace: P-04 */}

**The id.** Issued by Kintra, stable, and the parameter on every customer route: balance, transactions, tier eligibility, clubs, country and status. {/* trace: P-03, A-03 */}

**An account status.** One of `pending`, `active`, `suspended` or `reinstated` when you read it. You move it between `active`, `suspended` and `reinstated`; `pending` is a value you can be handed rather than one you can set. So suspending a customer in your product and suspending their membership are separate steps you take together. {/* trace: P-06, M-13 */}

**An XP balance status.** Separate from the account status, and either `active` or `locked`. Marking a balance is how you hold a customer while you look into something, and you set it back when you are done. The customer list reports the same state, so you can find every held customer without keeping your own list. {/* trace: P-07 */}

**Wallet addresses.** A customer's XP is held on chain against addresses Kintra manages for them, and a balance read sums the XP token across those addresses. Nothing you send names a wallet and you never handle a key. {/* trace: P-08, A-08 */}

Country, clubs and attributes exist too and are worth reading about when you need them rather than on day one. They are documented in the API reference; start from the [API reference overview](/api-reference/overview). {/* trace: P-04 */}

## The same person in two tenants

If you run two tenants, the same human is two customers with two ids. Their XP does not move between them and neither does their tier standing. Passing a customer id from one tenant to the other returns 404 with `USER_NOT_FOUND`, the same answer as an id that never existed, so a mixed-up id shows up as a missing customer rather than as leaked data. [Tenants](/concepts/tenants) covers the rest of that boundary. {/* trace: A-03, A-04, A-11 */}

## Where to go next

* [XP and the ledger](/concepts/xp-and-the-ledger) for what a customer's balance is and how it moves.
* [Tenants](/concepts/tenants) for the boundary a customer sits inside.
* [Quickstart](/quickstart) to create a customer and award XP now.