Documentation
SDK/Customers•8 min read

Customers

Connect app customers, track activity and preferences, and manage messages and journeys.

Browse Docs

Customers

Customers connects app-owned user identities, selected activity, communication preferences and managed payments. Your app keeps its authentication, sessions and business database. Each canonical notebook has separate test and live customer spaces.

This API requires a platform deployment and SDK release containing Customers. Check your installed SDK before using these exports; HTTP is also supported from PHP and other server runtimes.

Connect an app

An organization administrator opens Customers from the workbench add-view menu. Enable a customer space, configure its sender and install the shared project connection. Test credentials are installed only in development; production receives Live credentials only. Republish production after installing or replacing credentials. Task/review forks must not receive live customer data or credentials.

Platform-token clients can use client.customers.forNotebook(notebookId) to connect, provision, list, configure a sender and configure journeys. These operations require customers:read or customers:manage, as appropriate, and ownership of the canonical notebook. They do not require a local project record.

Identify app customers

Customers and Payments share one app identity per environment. Initialize the server client with PHPSandbox.app(); it reads the installed configuration and defaults to development outside production, production inside it. Use Test mode only in development; published apps use Live mode. Missing production configuration fails rather than using development access.

import { PHPSandbox } from '@phpsandbox/sdk';

const platform = PHPSandbox.app();
const runtime = platform.customers;
const customer = await runtime.identify({
  externalId: authenticatedUser.customerExternalId,
  email: authenticatedUser.email,
  name: authenticatedUser.name,
  source: 'landing-page',
});

Persist an opaque UUID on each app account as customerExternalId; separate databases must not reuse sequential IDs. Persist customer.id against the app account. Retrying the same external identity updates one customer. Matching email addresses never merge accounts. An email change removes marketing consent and does not clear delivery suppressions.

For a waitlist lead, use an app-generated stable lead identity. Once your app verifies that lead belongs to an authenticated account, call runtime.linkIdentity(customer.id, authenticatedUser.customerExternalId). Both identities resolve to the same customer. Linking to an identity belonging to another customer fails with a conflict; it does not silently merge accounts.

Activity and preferences

await runtime.preferences(customer.id, {
  subscribed: optedIn,
  source: 'signup-checkbox-v1',
});
await runtime.event(customer.id, {
  eventId: collection.id,
  name: 'collection.created',
  properties: { count: 1 },
});

Record preferences only after a deliberate customer choice. A signup or purchase does not grant marketing consent. Stable event IDs make retries safe; changed content under an existing ID is rejected. Report selected backend-confirmed business activity, not arbitrary client payloads or secrets.

Authorize the app user before every customer lookup or update. Derive the customer identity from the authenticated account, not from a freely submitted browser ID. Read current preferences with runtime.get(customer.id) so an email unsubscribe is reflected in your app.

Messages and journeys

runtime.send(customer.id, { requestId, subject, body, category }) queues a message. Preserve the request UUID on retries. Categories are service for requested/necessary service messages and marketing for promotional messages. Never relabel marketing to bypass unsubscribes. Templates accept {{name}} and {{email}}.

Owners can enable welcome, delayed setup and post-purchase journeys. Enabling includes eligible existing customers. Setup reminders stop when the configured activity arrives; purchase follow-ups require a paid linked transaction. Sending rechecks current customer preferences, connection state and journey state. Queued messages wait for sender readiness.

Development messages are delivered to the project inbox inside Customers → Messages. The rendered email, recipient, sender, unsubscribe link and receipt time are stored together; no external SMTP capture service is required. Production messages use a verified sending domain and the configured email provider. States distinguish queued, accepted, delivered, failed, suppressed and uncertain. Development inbox receipt is not proof of external email delivery. An uncertain prior attempt is never blindly retried. Production retries reuse the same saved payload and provider idempotency key within the supported window.

Marketing messages include unsubscribe links. Opening a link displays confirmation; confirming it records the preference. One-click unsubscribe POST requests are supported. Bounces and complaints suppress future messages, including service messages.

Pass optional customerId when creating a managed checkout or subscription. The customer must belong to the same notebook, organization and mode. Renewals retain the customer link. Payment verification, fulfillment and access remain governed by the existing payment contract. Historical orders are not linked by guessing email addresses.

HTTP contract

Use JSON, Accept: application/json and Authorization: Bearer SERVER_CREDENTIAL. Successful runtime responses wrap data.

MethodPath relative to the full runtime URLOperation
POST/identifyIdentify or update a contact
GET/:customerIdRead the app customer’s current profile/preferences
POST/:customerId/identitiesExplicitly link a verified app identity
POST/:customerId/eventsRecord selected activity
PUT/:customerId/preferencesRecord a subscription choice
POST/:customerId/messagesQueue a service or marketing message

Owner APIs are under /v1/platform/customers/sandboxes/:notebookId/:mode, authenticated with platform credentials. They expose connection management, sender/journey configuration and customer detail, full export and deletion under /people/:customerId. App runtime credentials cannot list the audience, export customer records or configure campaigns.

Deleting a customer removes identity links, activity and preference history, redacts retained message content and clears customer references from retained payment records.

Production email setup

Configure CUSTOMERS_RESEND_KEY and register the public /hooks/customers/email callback with the email provider. Set its signing secret as CUSTOMERS_RESEND_WEBHOOK_SECRET. Signed delivery, bounce, complaint, failure and suppression events enter the shared durable inbox; provider event IDs deduplicate retries. Unrelated event types do not trigger customer notifications.

Callbacks remain effective for older messages after the short polling recovery window ends. A message tag lets the callback recover a send whose response was lost. Delivery acceptance cannot overwrite an already delivered or failed state. Polling remains a recovery path, not the only source of delivery feedback.

Build, verify and publish

Use the actual application inside the workspace Preview: sign up, record consent, perform an activity, purchase through sandbox checkout, read Messages and follow unsubscribe. Payments setup supports an owned Development preview target for sandbox checkout and authenticated signed callbacks before publication.

The journey canvas separates saved drafts from activation. Starting from the panel defaults to future customers; existing customer enrollment is explicit. Waiting messages retain their saved content, activation event and version. Settings can copy development configuration to production drafts without copying customer records, consent, messages or payments. Review each production draft and its sender before activating it.

Historical synchronization and legacy accounts

Use historical: true when identifying an existing account. Supply its original joinedAt and, when available, lastActiveAt. Historical identification does not enroll signup journeys. Use historical: true on imported events as well; those events do not activate a customer or update recent activity.

For accounts with unknown communication preferences, an application may supply an explicitly reviewed legacyPolicy identifier. Customers shows this basis separately from explicit subscription. It does not create consent dates or consent records. Known unsubscribes and suppressions take precedence. Import them before expanding a legacy policy:

const customer = await runtime.identify({
  externalId: account.customerExternalId,
  email: account.email,
  joinedAt: account.registeredAt,
  historical: true,
  unsubscribed: true,
});
await runtime.preferences(customer.id, {
  subscribed: false,
  source: 'original-preference-system',
  occurredAt: account.originalUnsubscribeTime,
});

Use suppressionReason on identification to preserve known delivery suppressions. Identification cannot clear a suppression or unsubscribe. Import original preference timestamps only when they are known; do not substitute a registration or import date for a consent date. name: null clears a previously synchronized name.

Organization relationships and existing billing

Identify each member before synchronizing the full organization membership snapshot:

await runtime.organization({
  externalId: organization.externalId,
  name: organization.name,
  ownerExternalId: owner.customerExternalId,
  members: members.map((member) => ({
    externalId: member.customerExternalId,
    role: member.role,
  })),
});
await runtime.event(actor.customerId, {
  eventId: usage.id,
  name: 'ai.used',
  organizationExternalId: organization.externalId,
});

The application remains authoritative for accounts and membership. Events retain their individual actor and organization. Removed members cannot report subsequent organization activity.

Applications using an existing billing system can report a backend-confirmed positive payment through runtime.confirmPayment(organization.externalId, { paymentId, amountMinor, currency, paidAt, historical }). Verify the provider payment and organization ownership on your server first. Never call this from a browser success redirect. Zero amounts are rejected. Stable payment IDs deduplicate retries and conflicting payment facts are rejected. Historical payments preserve the first-payment date without creating a new conversion; returning payers do not become first-payment conversions.

Credit-limit follow-ups

Review and activate the credit-limit journey in Customers. It enrolls once per organization after a non-historical ai.used event followed by a non-historical credit.limit_reached event from the same actor, after journey activation. It addresses the current owner and waits 24 hours. Historical imports never enroll automatically.

Your application worker calls runtime.pendingFollowUps(), rechecks its authoritative payment, access and actual credit state, then calls runtime.resolveFollowUp(messageId, resolution). Supported resolutions are eligible, paid, credits_available and access_changed. Include custom allowances and credit resets in this check. Resolve immediately after checking, rather than saving an eligibility decision for later.

Eligible delivery runs in that request. Customers also rechecks the journey, recipient, unsubscribe, suppression, membership and confirmed payment state. A later background worker cannot reuse an expired eligibility check. Pausing the journey stops delivery; confirmed payment stops its pending follow-up.

Audience campaigns support reviewed recipient snapshots of up to 100,000 unique addresses. Larger lists display a bounded sample and offer a complete recipient download. Daily capacity still applies; a reviewed campaign automatically continues the next day after reaching capacity, without adding later matching customers.