> ## Documentation Index > Fetch the complete documentation index at: https://docs.payra.com/llms.txt > Use this file to discover all available pages before exploring further. # Customers > Your buyers as Payra customers, found by your own user id, so their cards can be saved and charged again. A **customer** is one of your workspace's customers: the same record your team sees under **Customers** in the Payra dashboard. Payment methods saved on a customer can be [charged](/payments) again without the buyer typing the card, and payments made with them are filed on that customer in the dashboard. Create each buyer as a customer from your server, with your own id for them (your user id, for example) as `reference`. You can keep Payra's `id` with your user, or skip that and look the customer up by `reference` whenever you need it. Call it when the buyer signs up, or the first time they pay with you. Calling it again later is safe (see below). ```bash theme={null} curl -X POST https://api-dashboard.payra.com/v1/customers \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "reference": "user_48213", "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+15555550123" }' ``` ```json Response theme={null} { "object": "customer", "id": "019e2b4c-7a1d-7c3e-9f20-5b8d4e6a1c30", "reference": "user_48213", "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+15555550123", "created_at": "2026-09-29T14:00:00.000Z" } ``` Every field is optional. `reference` is your id for the buyer, up to 100 characters, unique in your workspace. `phone` is in E.164 format (`+1` and ten digits for a US number). `name` is the name the dashboard shows; when you leave it out, the email is used as the name, or the `reference` when there is no email either, and `name` returns that. ```bash theme={null} curl "https://api-dashboard.payra.com/v1/customers?reference=user_48213" \ -H "Authorization: Bearer sk_test_..." ``` The list holds that one customer, or none. With Payra's id, `GET /customers/{id}` reads it directly. ## Creating again is safe When a customer of your workspace already has the `reference` you send, `POST /customers` creates nothing: it returns that customer, unchanged, with `200` instead of `201`, and ignores the other fields you sent. So you can call it at every sign-up or checkout without looking the buyer up first, and a retry after a timeout, or two requests arriving at the same time, never makes a second customer. Without a `reference`, every call creates a new customer. ## Saving and reusing a card A new buyer, or one paying with a new card: 1. `POST /customers` with your user id as `reference`, if you have not already. 2. [Create a payment method session](/payment-method-sessions) with that `customer`, and let [Elements](/elements) collect the card. Saving needs the billing postal code: collect it on your page and pass it when Elements confirms the session. 3. [Create the payment method](/payment-methods) with `account_holder_authorization: true`, your statement that the buyer agreed to keep the card on file. Payra verifies the card with the processor and saves it on the customer; the method reads `usage: saved`. 4. [Charge it](/payments) for the order. If your checkout lets the buyer choose whether to keep the card, create the session with their `customer` either way and send the choice in step 3: `account_holder_authorization: true` to save it, or `usage: "one_time"` to charge it once without saving. The payment is filed on the customer in both cases, and the buyer can change their mind without the card fields being reset. To check a card before the buyer buys anything, stop after step 3. No payment is created. The verification is a small authorization that the processor voids at once (on Dhango, \$1.00); it may still show on the buyer's statement as pending for a short while. A returning buyer: 1. `GET /customers?reference=…` to find their customer (or use the `id` you kept). 2. [List their saved payment methods](/payment-methods#list-a-customers-saved-payment-methods) and show them. 3. Charge the one they pick with `POST /payments`, passing its `payment_method`, and `customer` if you like. A buyer who deletes a card in your store: [detach it](/payment-methods#detach-a-saved-payment-method), so it can no longer be charged and leaves their file in the dashboard. Buyers who already had an account with you before you started using Payra need nothing done in advance. The first time one pays by card, `POST /customers` with their user id creates their customer on the spot, and they enter the card once. Cards saved with a previous processor stay with that processor. ## What else comes with a customer * **Receipts from Payra.** When the customer has an email and the workspace's **Email payment receipts to customers** setting is on, charging one of their saved payment methods emails them Payra's payment receipt. Turn the setting off if you send your own. See [Payments](/payments). * **The dashboard.** Your team sees the customer, their saved cards and their payments, and can remove a card there too; its payment method then reads `detached`. * **No environment.** Customers belong to the workspace, not to sandbox or live: a sandbox key and a live key read the same ones. Payment methods do belong to one environment, so a customer's sandbox cards are never listed or charged with a live key. Customers created in the dashboard, or synced from an ERP, can be read and listed too; their `reference` is `null`. A workspace whose customers come from an ERP integration cannot create them through the API: `POST /customers` answers `403 customers_managed_by_erp`. ## Scopes and errors Creating needs `customers:write`; reading and listing need `customers:read`. The list runs newest first and [pages](/pagination) with `limit` and `starting_after`. | Code | Why | | - | - | | `parameter_invalid` (400) | A malformed `email`, a `phone` not in E.164, a `reference` longer than 100 characters, a `limit` out of range, or a `starting_after` that is not a customer of your workspace; `param` names the field | | `resource_missing` (404) | No customer with that id in your workspace | | `customers_managed_by_erp` (403) | The workspace's customers come from its ERP integration |