> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront cache, analytics, and Shop Pay

> Configure commerce-safe caching, inspect storefront traffic and checkout redirects, and gate optional Shop Pay activation.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Enable performance and commerce features without caching personalized state or claiming checkout readiness that has not been verified.

## Prerequisites

* A connected Shopify storefront
* A production deployment after the latest settings change for active managed caching

## Workflow

<Steps>
  <Step>
    Choose `shopify_safe` or `origin_only` as the cache profile.
  </Step>

  <Step>
    Enable or disable StackShift storefront analytics.
  </Step>

  <Step>
    If using Shop Pay, confirm checkout routing and either use a detected Hydrogen `ShopPayButton` or explicitly confirm the component.
  </Step>

  <Step>
    Redeploy after settings changes, then inspect cache status and storefront analytics.
  </Step>
</Steps>

## Shopify-safe cache behavior

* `shopify_safe` can become active only when the platform edge-cache flag is enabled, the production URL uses a StackShift-managed hostname, and the active deployment is newer than the settings update.
* Only GET and HEAD requests on the primary managed hostname are candidates for positive cache headers.
* `/cart`, `/account`, `/checkout`, `/customer`, and `/api/customer` paths bypass; Authorization and Cookie requests bypass; non-GET/HEAD requests bypass.
* A response that sets a cookie is forced to `private, no-store`.
* Public pages receive default `public, max-age=60, s-maxage=300`; common immutable assets receive `public, max-age=31536000, immutable` unless the application already supplied Cache-Control.
* `origin_only` applies no StackShift positive cache profile. For external CDNs, the analytics response returns the exact bypass policy operators must reproduce.

## Analytics contract

* Analytics must be enabled in storefront settings or the endpoint returns Shopify-disabled.
* The response includes request/page-view/visitor/status/duration summary data, a timeseries, the top 50 paths, checkout redirect count, and current cache status.
* Checkout redirects count observed redirect responses associated with the checkout redirect breakdown; they are not completed-order or conversion analytics.
* Analytics use StackShift ingress data. Shopify sales, orders, and customer analytics remain in Shopify.

## Shop Pay readiness

* Shop Pay is off by default and is never enabled in Shopify by StackShift.
* When requested, launch checks require a verified production target, HTTPS/TLS readiness, confirmed checkout routing, and a detected or explicitly confirmed Shop Pay component.
* Hydrogen detection looks for `ShopPayButton`; generic storefronts can use the explicit component confirmation setting.
* The merchant must still enable and configure Shop Pay in Shopify admin and test the actual checkout flow.

## Allowed settings only

* Accepted keys are `cache_profile`, `analytics_enabled`, `shop_pay_enabled`, `shop_pay_component_confirmed`, and `checkout_routing_confirmed`.
* Credential-, secret-, token-, and password-shaped settings are rejected. Credentials belong only in environment credential fields.

## Expected result

<Check>
  Public production traffic has explicit cache behavior, personalized commerce routes bypass caching, and optional Shop Pay readiness is backed by production checks.
</Check>

## Common failures

<Warning>
  * Cache settings changed but production was not redeployed
  * Production uses an external hostname so StackShift cannot enforce managed cache rules
  * Analytics are disabled
  * Shop Pay was requested without HTTPS, verified production credentials, checkout confirmation, or a component signal
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Configure Shopify storefront hosting" href="/shopify/storefront-hosting-setup">
    Connect Hydrogen or a confirmed Node storefront, obtain Storefront API credentials, isolate targets, and verify Shopify access.
  </Card>

  <Card title="Storefront previews, promotion, and domains" href="/shopify/previews-promotion-and-domains">
    Test on generated URLs and promote an active preview’s exact immutable image to production without rebuilding it.
  </Card>

  <Card title="Shopify webhooks and observability" href="/shopify/webhooks-and-observability">
    Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.
  </Card>
</CardGroup>