Visitor identity, email and consent

Antla distinguishes the store connection from the visitor’s identity. The SDK key selects a store. uniqueUserId tracks a visitor within that store.

Save and reuse visitor IDs

Call GET /requests-left when initializing an API-driven UI if you want an email pre-check. Save any non-null returned uniqueUserId, and reuse it for:

• Later /requests-left calls.
• Customer registration.
• Generation submission.
• Generation polling.

A new visitor ID can also be returned after registration or generation. Preserve the saved ID when a response returns null. Do not write the string "null" into a request.

Do not replace Antla’s returned ID with a Shopify customer ID, an email, or an arbitrary client-generated UUID. An unknown ID can fall back to the service’s IP-based identity behavior; it is not a public create-visitor API.

Namespace state by merchant and environment. On shared devices, account changes and merchant switches, apply your app’s own identity-reset policy.

Interpret the email gate

requestsLeft	Meaning
Greater than 0	Remaining try-ons before email registration becomes required
0	Collect/register email before another permitted generation
-1	Email collection is disabled or this visitor already has an email

This value is not the merchant’s credit balance and is not the per-user try-on allowance. A generation can fail on credits or a customer try-on limit even when the email gate is open.

totalRequests is how many try-ons have already been counted in the current email period. That period is the current UTC day, or the activation time when email collection was turned on earlier today. The rolling customer try-on limit is a separate 24-hour check. Merchant credits are separate again.

Two email paths

Register first

{
  "email": "shopper@example.com",
  "name": "Alex",
  "uniqueUserId": "SAVED_VISITOR_ID"
}

Send this to POST /customer-register. Omit fields you do not have. Save the returned identity, then continue generation.

Register while starting a generation

Add customerEmail to a valid POST /generations request. The service registers the visitor before the generation flow. Pass an existing visitor ID when available.

If the server responds with HTTP 403 and code: "EMAIL_REQUIRED", collect email and retry that rejected attempt with the required information. This is different from an ambiguous network failure: the explicit email rejection indicates generation was not queued by that request.

Registration is not login

Registration saves the email and name on an Antla visitor identity. It is not Shopify Customer Account authentication, ownership verification, a customer-management API, or a general change-email operation.

Registration can return an existing visitor without changing that visitor’s email. If the server falls back to the client IP and that visitor already has an email, the response is 400 Email already registered. Do not use this endpoint to switch accounts. A backend that sends many shoppers through one IP should pass each shopper’s saved uniqueUserId. See Partner apps.

Consent

moreLooksConsent is an optional boolean on generation. Send the shopper’s actual choice. Omit it when no choice was collected; do not invent consent or prefill true.

POST /customer-register does not accept a consent field. Email collection, acceptance of terms and consent to further marketing are different decisions in your UI.

The SDK renders the merchant’s terms and more-looks controls. A custom UI needs its own wording and should follow that merchant’s policy. These endpoints do not define how long photos or visitor records are kept.

Klaviyo behavior

Customer registration can enqueue profile synchronization. A generation includes generation-linked Klaviyo payloads when customerEmail is supplied on that generation request. If you need that behavior, keep passing the known email after registration, together with the corresponding consent choice.

Successful HTTP registration does not confirm downstream delivery, list subscription, campaign enrollment or every marketing side effect. Those depend on merchant configuration and asynchronous processing.

Data handling

Avoid storing shopper photos or email in diagnostic logs. Keep job IDs, visitor IDs, image URLs and cart IDs out of shared URLs or broadly accessible analytics. Use your application’s authenticated access controls when returning results to signed-in users.

The documented Headless API has no customer deletion, export or photo-deletion endpoint. Coordinate lifecycle and retention requirements with Antla rather than assuming a behavior that is not specified.