Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Customers
description: How Spree models customer accounts — registration, authentication, addresses, order history, store credits, and guest checkout behavior.
---
## Overview
Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
```mermaid
erDiagram
Customer ||--o{ Order : "places"
Customer ||--o{ Address : "address book"
Customer ||--o| Address : "default ship/bill"
Customer ||--o{ Wishlist : "has many"
Customer ||--o{ StoreCredit : "has many"
Customer ||--o{ GiftCard : "holds"
Customer ||--o{ CompanyMembership : "buys for"
CompanyMembership }o--|| Company : "belongs to"
Customer }o--o{ CustomerGroup : "segmented by"
Customer {
string email
string first_name
string last_name
string phone
}
Order {
string number
string payment_status
string fulfillment_status
}
Address {
string label
string first_name
string last_name
string company
string address1
string address2
string city
string postal_code
string state_code
string country_code
string phone
}
Wishlist {
string name
boolean is_default
}
```
## Registration
<CodeGroup>
```typescript Store SDK
const { token, user } = await client.customers.create({
email: '[email protected]',
password: 'password123',
password_confirmation: 'password123',
first_name: 'John',
last_name: 'Doe',
})
// token => JWT token for subsequent authenticated requests
// user => { id: "cus_abc123", email: "[email protected]", first_name: "John", ... }
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "password123",
"password_confirmation": "password123",
"first_name": "John",
"last_name": "Doe"
}'
```
</CodeGroup>
<Note>
The Store API flow above is **customer self-registration** — the customer sets a password and gets a JWT back. To [create a customer record from the back office](/developer/sdk/admin/resources) (importers, CRM sync, phone orders), use the [Admin SDK](/developer/sdk/admin/quickstart) instead. No password is set, so it's a managed record rather than a sign-up:
```typescript Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
const customer = await client.customers.create({
email: '[email protected]',
first_name: 'John',
last_name: 'Doe',
tags: ['wholesale'],
})
```
</Note>
## Login
<CodeGroup>
```typescript Store SDK
const { token, user } = await client.auth.login({
email: '[email protected]',
password: 'password123',
})
// Use the token for authenticated requests
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "password123"
}'
```
</CodeGroup>
The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the [`Authorization: Bearer <token>`](/api-reference/store-api/authentication) header.
## Token Refresh
Refresh an expiring token to keep the session alive. For how `client.auth.login` and `client.auth.refresh` fit into configuring the SDK for guest vs customer (JWT) auth, see the [SDK authentication guide](/developer/sdk/authentication):
<CodeGroup>
```typescript Store SDK
const { token, refresh_token } = await client.auth.refresh({
refresh_token: existingRefreshToken,
})
// Persist the rotated refresh_token for the next refresh
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{ "refresh_token": "rt_xxx" }'
```
</CodeGroup>
## Password Reset
Password reset is a two-step flow. First, request a reset email. Then, use the token from the email to set a new password.
### Step 1: Request Reset
<CodeGroup>
```typescript Store SDK
await client.passwordResets.create({
email: '[email protected]',
redirect_url: 'https://myshop.com/reset-password',
})
// Always returns { message: "..." } — even if the email doesn't exist
// This prevents email enumeration
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/password_resets' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"redirect_url": "https://myshop.com/reset-password"
}'
```
</CodeGroup>
The optional `redirect_url` parameter specifies where the password reset link in the email should point to. The token will be appended as a query parameter (e.g., `https://myshop.com/reset-password?token=...`). If the store has Allowed Origins configured, the `redirect_url` must match one of them.
This fires a `customer.password_reset_requested` event with the reset token in the payload. If you're using the `spree_emails` package, the email is sent automatically. Otherwise, subscribe to this event to send the reset email yourself (see [Events](/developer/core-concepts/events)).
### Step 2: Reset Password
<CodeGroup>
```typescript Store SDK
const { token, user } = await client.passwordResets.update(
'reset-token-from-email',
{
password: 'newsecurepassword',
password_confirmation: 'newsecurepassword',
}
)
// Returns JWT token + user (auto-login)
```
```bash cURL
curl -X PATCH 'https://api.mystore.com/api/v3/store/password_resets/RESET_TOKEN' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"password": "newsecurepassword",
"password_confirmation": "newsecurepassword"
}'
```
</CodeGroup>
On success, the user is automatically logged in and a JWT token is returned. The reset token expires after 15 minutes (configurable via `Spree::Config.customer_password_reset_expires_in`) and is single-use (changing the password invalidates it).
## Newsletter Subscriptions
Headless storefronts often need to collect newsletter signups before account creation (footer forms, popup overlays). The Store API exposes a double opt-in subscription flow that mirrors the password reset webhook pattern.
### Step 1: Subscribe
<CodeGroup>
```typescript Store SDK
await client.newsletterSubscribers.create({
email: '[email protected]',
redirect_url: 'https://myshop.com/newsletter/confirm',
})
// Returns the NewsletterSubscriber (verified: false for guests)
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"redirect_url": "https://myshop.com/newsletter/confirm"
}'
```
</CodeGroup>
The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's Allowed Origins — URLs that do not match are silently dropped from the webhook payload (secure-by-default).
This fires a `newsletter_subscriber.subscription_requested` event whose payload includes `email`, `verification_token`, and the validated `redirect_url`. Subscribe to this event from your storefront's webhook handler to send the confirmation email — the link in the email should point to `<redirect_url>?token=<verification_token>`. The bundled `spree_emails` package also listens to this event and sends a default confirmation email if you're not running a headless storefront.
If the request is authenticated via a customer JWT and the JWT's email matches the subscribed email, the subscription is **auto-verified** and no event is fired (the user has already proven email ownership).
### Step 2: Verify
<CodeGroup>
```typescript Store SDK
await client.newsletterSubscribers.verify({
token: 'token-from-email',
})
// Returns the verified NewsletterSubscriber
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers/verify' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{ "token": "token-from-email" }'
```
</CodeGroup>
On success, the subscriber is marked verified. If the subscription is linked to a customer record, that customer's `accepts_email_marketing` flag is also set to `true`. Consent is preserved across registration: if a guest subscribes and later registers with the same email, the existing subscriber is reused — registration won't accidentally reset their opt-in state.
## Customer Profile
<CodeGroup>
```typescript Store SDK
// Get current customer
const customer = await client.customer.get()
// {
// id: "cus_xxx",
// email: "[email protected]",
// first_name: "John",
// last_name: "Doe",
// default_shipping_address: { ... },
// default_billing_address: { ... },
// addresses: [{ ... }, { ... }],
// }
// Update profile
const updated = await client.customer.update({
first_name: 'Jonathan',
accepts_email_marketing: true,
})
```
```bash cURL
# Get current customer
curl 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>'
# Update profile
curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
```
</CodeGroup>
## Customer Resources
Authenticated customers have access to these resources:
| Resource | Description |
|----------|-------------|
| [**Addresses**](/developer/core-concepts/addresses#customer-address-book) | Billing and shipping addresses with default selection |
| [**Orders**](/developer/core-concepts/orders#order-history) | Past order history |
| **Credit Cards** | Saved credit cards for checkout |
| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
| **Store Credits** | Balance assigned by the store, usable at checkout |
| **Gift Cards** | Gift cards owned by or assigned to the customer |
| **Wishlists** | Saved product lists |
## Guest Checkout
Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Token`) to identify the cart. See [Orders — Cart](/developer/core-concepts/orders#cart) for details.
## Related Documentation
- [Account (Store SDK)](/developer/sdk/store/account) — Task-oriented walkthrough of registration, login, profile, addresses, and order history
- [Addresses](/developer/core-concepts/addresses) — Customer address management
- [Orders](/developer/core-concepts/orders) — Order history and checkout
- [Authentication](/developer/providers/sso) — Custom authentication setup
- [Staff & Roles](/developer/core-concepts/staff-roles) — Admin users and permissions