Integrate a partner app

Use the Headless API when your app owns the try-on interface. Try-on is scoped to that merchant’s Shopify catalog. Your app loads products from Shopify or its own catalog.

Supported integration model

A merchant connects Headless API inside Antla and supplies the API base URL and Headless key for that installation. Storefront tokens are not required. Your app uses those values to start try-ons for products assigned to that merchant’s Antla Funnels.

There is no partner-wide key, partner OAuth flow, API for creating Headless connections, or endpoint for a catalog outside Shopify. Each merchant connects Headless API in Antla and gives you that installation’s API base URL and key. If they also connected Headless SDK, the key is the same value.

Merchant onboarding checklist

1. The merchant installs Antla and assigns products to Funnels.
2. The merchant completes Headless API setup. SDK is optional and only needed if you call /context or embed <antla-block>.
3. Your app records the merchant’s API base URL and Headless key as one configuration.
4. Verify a Funnel lookup or a generation. Do not require /context for API-only merchants.
5. Store visitor IDs and job records under that merchant’s identity.
6. Run one authorized generation and the intended cart or checkout flow.
7. Record an operational owner for key refresh, disconnect and support.

Do not reuse one merchant’s key, funnel IDs, visitor IDs, product IDs or job IDs for another merchant.

Direct client or backend

Pattern	Good fit	Responsibilities
Client → Antla	Storefront or native app using the public SDK-key model	Client UI, identity storage, error handling and polling
Client → your backend → Antla	Existing authenticated application with centralized workflows	Tenant authorization, shopper/job mapping, load controls, request budgets and reliable job persistence

A shared backend egress IP aggregates Antla requests across shoppers. The rate limiter uses an IP counter shared with other Headless and App Proxy calls. Anonymous identity can also fall back to IP when a saved visitor ID is absent. Evaluate this before proxying all traffic.

There is no documented partner-specific end-user IP forwarding contract. Do not fabricate client IP headers or assume that adding an arbitrary forwarding header solves identity or rate limits. Coordinate proxy behavior with Antla and test separate shopper sessions behind the same egress.

Keep jobs attached to the right user

When your backend receives a successful generation response, persist:

{
  "merchantId": "your-merchant-id",
  "appUserId": "your-internal-user-id",
  "antlaJobId": "c45451c0-b02c-4c90-8c6e-0779edb01996",
  "antlaVisitorId": "visitor-id-or-null",
  "productId": "gid://shopify/Product/123",
  "variantId": "gid://shopify/ProductVariant/456",
  "state": "processing"
}

This is your application’s record, not an Antla endpoint schema. Authorize access against your own merchant and app user before polling or returning a result. Antla’s job lookup is scoped to the store; uniqueUserId is not job authorization.

Implement the flow

Follow Custom UI workflow. Identify the Funnel, prepare the image, handle email if required, start once, save the returned job ID, and poll to a terminal result.

Use the reference HTTP client, or generate a client from OpenAPI. Generated transport code still needs your identity, consent, retry, and UI lifecycle logic.

Delivery semantics

There is no documented idempotency key or job lookup by your request ID. If a POST times out after being sent, the outcome can be unknown. Do not automatically resubmit it. Mark that attempt as uncertain and give the shopper a clear recovery path.

Once you have a job ID, resume polling that same job after transient network failure. Polling is the completion mechanism; there is no documented completion webhook.

Cart and attribution

Use Shopify Storefront Cart API for purchases. The Antla API does not create carts or add products. If you want parity with the browser SDK’s cart metadata, see Cart integration. Adding metadata alone is not a guarantee of a discount or a complete analytics integration.

Integration boundaries

Antla email registration is not Shopify customer authentication or proof of consent. More-looks consent is an explicit generation field; preserve the shopper’s choice. The API does not expose customer deletion, result listing, generic events, email sending or social-sharing operations.

Before a merchant launch, read Identity and consent, Errors and rate limits, and the launch checklist.