CRM

The CRM module manages profile records and audience subscriptions for your store. Profiles are store-scoped — each store has its own profile list. A profile can be linked to orders and audience subscriptions, and can authenticate via email magic codes.

Key Concepts

Profile vs Account

• Account — platform-level auth identity. One person, one Account across all stores.
• Profile — store-level CRM record with one email, verification state, status, and taxonomies. Each store has its own view of a profile.

Taxonomies

Profile classification and searchable custom fields are stored as taxonomies — the same content model used across the platform. There is no direct profile tags field; tags and segments are taxonomy entries.

Email

Profiles have a single email. The initialize flow creates an anonymous guest profile; the email is set once the profile authenticates with requestCode / verify, calls connect, or is updated by an admin.

Profile Endpoints

Create Profile (Admin)

Creates a new profile. If a profile with the same email already exists, returns the existing one (idempotent).

Initialize Profile (Public)

Public endpoint for end users. Creates an anonymous guest profile and returns an auth token. No email required — use this to get a profile session before any identity is known. The returned token can later be upgraded by calling connect or requestCode + verify.

Connect Profile (Public)

Attaches an email to the current profile session (or returns/creates a profile matching the email). Returns a fresh auth token.

Request Auth Code (Public)

Sends a verification code to the given email address. Use this to start a profile login flow.

Verify Auth Code (Public)

Exchanges a verification code for an auth token, marking the profile as verified.

Refresh Token (Public)

Exchanges a refresh token for a new access token.

Get Current Profile

Returns the currently authenticated profile based on the bearer token.

Get Profile

Find Profiles

Search and list profiles.

Update Profile

Merge Profiles

Merges a source profile into the target. The source is permanently deleted (GDPR-compliant). Orders and audience subscriptions are re-pointed to the target profile.

Revoke Session Token

Revokes a single active session for a profile.

Revoke All Session Tokens

Revokes every active session for a profile (logout everywhere).

Profile Object

{
  "id": "uuid",
  "store_id": "uuid",
  "email": "[email protected]",
  "verified": true,
  "status": "active",
  "taxonomies": [],
  "promo_usage": [],
  "auth_tokens": [],
  "verification_codes": [],
  "created_at": 1234567890,
  "updated_at": 1234567890
}

Audiences

Audiences are subscriber groups used for content gating, newsletters, and paid memberships. They live under the CRM module as sdk.crm.audiences.*.

Key Concepts

An audience is a subscriber group with two dimensions:

• Type: standard (free) or paid (Stripe checkout)
• Confirmation: Optional double opt-in via an email template (confirmTemplateId)

Use cases: newsletter subscriptions, premium memberships, course access, tiered content.

Create Audience

Get Audience

Look up an audience by ID or by key.

Find Audiences

Update Audience

The type cannot be changed after creation, but you can update the key, status, and confirmation template.

Subscribe to Audience

Subscribe a profile to an audience. Behavior depends on the audience configuration:

• Standard, no confirmation: Subscription is immediately active
• Standard, with confirmation: Subscription is pending until the user clicks the confirmation link
• Paid: Returns a Stripe checkout URL

Check Access

Check if the current profile has access to an audience.

Get Subscribers

List subscribers for an audience (admin only).

Add Subscriber

Add a subscriber by profile ID (admin only). Skips if already subscribed.

Remove Subscriber

Typical Flows

E-commerce Checkout

// 1. Initialize a guest profile session
const token = await sdk.crm.initialize();

// 2. Attach the shopper's email
await sdk.crm.connect({ email: shippingAddress.email });

// 3. Checkout a cart — the authenticated profile is resolved from the token
const cart = await sdk.eshop.cart.current();
await sdk.eshop.cart.update({
  id: cart.id,
  items: [...],
  shipping_address: {...}
});
const order = await sdk.eshop.cart.checkout({ id: cart.id });

Newsletter Subscribe with Double Opt-in

// 1. Initialize + connect to get a profile
await sdk.crm.initialize();
const { id: profileId } = await sdk.crm.connect({ email: "[email protected]" });

// 2. Subscribe to the audience (sends confirmation email)
await sdk.crm.audiences.subscribe({
  id: audienceId,
  profileId,
  confirmUrl: 'https://yoursite.com/confirm'
});

Profile Login (Magic Code)

// 1. Ask for a code
await sdk.crm.requestCode({ email: "[email protected]" });

// 2. User enters the code from their email
const token = await sdk.crm.verify({
  email: "[email protected]",
  code: "123456"
});

// 3. Persist token.refresh_token and use token.access_token for subsequent calls