Assignment proxy

The storefront runtime asks this Shopify app-proxy endpoint which variant a visitor should see; the response drives every test type.

What it does

The assignment endpoint takes an anonymous visitor id and returns the visitor's variant for every live experiment on the shop. The app embed calls it once per page and then applies the results — a redirect, a template or theme parameter, or a signal your JavaScript reads through window.abtest.

It is served under the Shopify app proxy, so it lives on the merchant's own storefront domain rather than on the app host. A typical mounted path looks like /apps/ab/assign, where /apps/ab is the proxy prefix Shopify forwards to the app. The visible path depends on the merchant's app-proxy configuration, so treat /apps/ab/assign as an example, not a fixed URL.

Why it runs through the app proxy

Routing through the Shopify app proxy — instead of a cross-origin API on the app host — gives the storefront runtime three properties it depends on:

• Same-origin requests. The call is first-party to the storefront, so there is no CORS preflight on the critical path.
• First-party cookies. Cookies set on the storefront origin survive Safari's Intelligent Tracking Prevention.
• A signed shop. Shopify adds an HMAC signature the request is authenticated against, so the shop identity cannot be forged by a client.

Request

The endpoint responds to a GET request forwarded by the Shopify app proxy. Shopify appends its own signed parameters (including shop and the HMAC signature); the runtime supplies the rest as query parameters.

Targeting inputs — device, new vs returning, country, UTM parameters, referrer, and cookies — are read from the forwarded request itself, not passed as explicit parameters. See audience targeting.

Response

The endpoint always returns JSON with Cache-Control: no-store. On success the body has three fields:

{
  "assignments": [
    {
      "experimentId": "exp_123",
      "type": "url",
      "variantId": "var_b",
      "deferred": false,
      "variants": [
        { "id": "var_a", "isControl": true,  "config": { ... } },
        { "id": "var_b", "isControl": false, "config": { ... } }
      ]
    }
  ],
  "clientIntegrations": [ ... ],
  "preview": false
}

Assignment entry fields

Manual-trigger and preview behaviour

Two query parameters change how enrolment works:

• Manual trigger. For a manual-trigger test the endpoint computes the visitor's bucket but does not enrol them until the runtime calls back with activate=<experimentId>. That callback is what isHypothesisActive() issues when the visitor reaches the point you decided marks the test. Until then the entry comes back with deferred: true.
• Preview. A preview value forces one experiment to a chosen variant, skipping bucketing, and is validated against the current live experiments so a stale value is dropped. When a preview applies, the top-level preview field is true so the runtime skips caching and tracking.

Failure handling

The endpoint is built to fail open — a broken app must never break the storefront:

• A missing shop or a vid that fails validation returns { "assignments": [] } with status 400.
• An unknown or uninstalled shop returns an empty assignments array with status 200, not an error.
• If a single experiment throws while being resolved, it is skipped and logged; the remaining experiments still return their assignments.