CustomersService class (accessed via client.customers) exposes the customer record as a first-class API resource — meant for integrations that manage authentication outside Galactic Core.
Two integration paths. If your storefront uses Galactic Core’s built-in auth (
/v1/auth/register, /v1/auth/login, etc.), prefer the AuthenticationService — it creates and links the customer record for you. Use CustomersService when you’re bringing your own identity provider (Auth0, Clerk, Cognito, Firebase, NextAuth, SSO, etc.) and want to provision the Galactic Core customer record directly from your backend. See Customers and Auth for the full decision matrix.Sandbox isolation: Customer records created with a
tybrite_sk_test_* key exist only in the sandbox environment and are never visible to production keys. Every response includes a Tybrite-Environment: sandbox | production header confirming which environment resolved.Profile Management
createCustomer
Provision a Galactic Core customer record. The customer exists immediately and can place orders, hold a cart, leave reviews, etc. — but no Galactic Core login credentials are created. Authentication remains the responsibility of your external identity provider.
Pass external_id to store your upstream user identifier (Auth0 sub, Clerk user.id, etc.). It’s unique per store + environment, so subsequent reads can look up the Galactic Core customer by that identifier without keeping a side-table.
Pass marketing_consent to record whether the customer opted in to marketing communications. It defaults to false (opt-in) — only set it to true when the customer affirmatively checks a marketing opt-in box on your storefront. When true, the customer becomes eligible to be subscribed to the store’s connected marketing tools.
Secret Key only. Call this from a secure server-side environment — typically a webhook or post-signup hook in your identity provider.
201:
A newly created customer starts at the
bronze tier with no purchase history, so last_purchase and store_metrics are null until their first order. The tier rises through silver, gold, and platinum as the customer’s lifetime spend grows.The customer’s marketing opt-in can be changed later via
updateCustomer (e.g. when a
signed-in shopper toggles email preferences in their account). Pass
requestBody: { marketing_consent: false } to opt them out.createCustomer returns { customer }. getCustomer returns the customer fields at the top level.getCustomer
Retrieve a customer’s profile, including store metrics and purchase history. This is the endpoint your “My Account” page calls. The response includes store_credit_balance — the customer’s redeemable store-credit balance, which can be applied at checkout via apply_store_credit on createOrder.
Sign an xExternalAuth assertion in your backend (see Customers and Auth for the signing helper) and pass it through:
Using Galactic Core auth instead?
Using Galactic Core auth instead?
If your storefront authenticates customers through Galactic Core (Path A), pass the customer’s session JWT as Provide exactly one of
xAuthToken in place of xExternalAuth:xAuthToken or xExternalAuth. Both → 400. Mismatch with the path id → 403.200 — the customer fields are returned at the top level (not wrapped in a customer key):
address, last_purchase, and store_metrics are null until the customer has supplied an address and made a purchase. tier is one of bronze / silver / gold / platinum, derived from purchase history.updateCustomer
Partially update a customer’s profile. Only the fields you supply are modified. Typical caller: a “Save changes” button on the customer’s account page.
200 — the updated profile, wrapped in a customer key:
Using Galactic Core auth instead?
Using Galactic Core auth instead?
xAuthToken or xExternalAuth. Both → 400. Mismatch with the path id → 403.updateCustomer returns { customer }. Unwrap the customer key to get the resource.Saved addresses
Let a signed-in shopper keep a personal address book — multiple billing and shipping addresses they can reuse at checkout instead of re-typing them every time. Pre-fill your checkout form fromlistAddresses, or pre-select the shopper’s default shipping/billing address.
These are customer-self operations: they work with a publishable key (safe to call from the browser), but require the shopper’s session token in xAuthToken. The token must resolve to the customer in the id path parameter, otherwise the call returns 403.
Single default per kind. Setting an address as the default for shipping (
is_default_shipping) or billing (is_default_billing) automatically clears any previous default of the same kind, so there’s always at most one default shipping address and one default billing address.listAddresses
Return the shopper’s saved addresses, defaults first. Use this to render their saved addresses at checkout.
Response (200)
createAddress
Save a new address to the shopper’s address book. full_name, line1, city, and country are required; everything else is optional. address_type is one of shipping, billing, or both (default both).
Response (201)
updateAddress
Partially update a saved address — only the fields you supply are changed. Pass the address id as addressId.
deleteAddress
Remove an address from the shopper’s address book.
Customer Utilities
Authentication Flow
ThegetCustomer and updateCustomer methods require a customer session JWT (xAuthToken) in addition to your API key. Obtain the token via the AuthenticationService — either through login or verifyOtp.
createCustomer is intentionally Secret Key only — it is an admin/CRM operation (e.g. bulk imports) and does not involve customer authentication. No xAuthToken is required or accepted.