Build e-commerce storefronts

A digital commerce team runs the storefront of an online store on a commerce platform it operates, such as Magento or WooCommerce. Catalog and product pages are the same for every visitor and must stay fast during traffic peaks, while prices and stock change during the day. The cart, the checkout, and the pages of a signed-in visitor are different for every visitor and must never come from a shared copy. This page configures an application in front of the store that caches the catalog, sends cart, checkout, and session traffic to the store, and purges a product page when it changes. The result is measured by time to first byte on catalog and product pages, the time from a price or stock change to a live page, and the share of catalog requests that never reach the commerce platform.

This use case does not cover protecting login and checkout against bots. For that, refer to Block account takeover on login and checkout flows.

Prerequisites

• An application that serves the store through a connector and a workload. To create them, refer to Applications quickstart.
• Application Accelerator on that application, which the Bypass Cache and Forward Cookies behaviors require. To turn it on, refer to Turn on Application Accelerator.
• A personal token, for the API and the purge calls. To create one, refer to Personal tokens.
• The paths and the session cookie of your store. This page uses /products/ and /category/ for the catalog, /cart, /checkout, and /account for per-visitor pages, session_id for the cookie the store sets when a visitor starts a session, and www.example.com for the domain. Replace each value with your store’s in every step.

Required products

Reference architecture

This page builds the Origin-hosted commerce platform storefront: an application in front of a store that keeps rendering every page.

Read the diagram from the application outward. Every request passes through its rules, which split it into three paths: catalog pages that Cache can answer, per-visitor pages that must reach the store, and images that Image Processor transforms. All three paths end at the same connector, because the commerce platform remains the only origin. The loop from the store back to Cache is the purge, which keeps cached pages in step with the catalog.

Dataflow

1. A visitor’s request reaches the workload on the store’s domain, which hands it to the application, and Rules Engine reads its path and its session_id cookie in the Request Phase.
2. A catalog or product page requested without a session cookie is served from Cache. On a miss, the application fetches it from the store through the connector and caches it.
3. A cart, checkout, or account request, or any request that carries the session cookie, bypasses the cache and goes to the store through the connector.
4. An image request goes through Image Processor, which resizes or converts the original fetched from the store, and Cache keeps each variation.
5. When a product changes, the commerce platform calls the Real-Time Purge API, which removes the affected product pages from Cache before their TTL ends.
6. The next request for a purged page reaches the store, and the new version is cached.

Components

• application: the Platform Resource in front of the store. It holds the cache settings and the rules that decide, request by request, whether a page is cached or bypassed.
• Rules Engine: the Feature of the application that matches paths and cookies. The cache bypass for a signed-in visitor depends on a cookie condition, because the same product path is shared for an anonymous visitor and private for a signed-in one.
• connector: the Platform Resource that reaches the store. Every path, cached or not, ends at it, because the store renders every page.
• Cache: stores catalog and product pages, so repeated requests for them never reach the store.
• Real-Time Purge: the Platform Resource that removes a changed product page from Cache before its TTL ends, so a price or stock change goes live without waiting for the page to expire.
• Image Processor: resizes and converts product images on request, so the store keeps one original per image.
• commerce platform: the integration that is the origin and the content source. It renders every page, owns the cart and the checkout, and sends the purge when the catalog changes.

Other designs for this use case

• Statically generated headless commerce storefront: for catalogs that change a few times a day, where a site generator pulls products from the commerce platform’s API at build time. Catalog pages are prebuilt in Object Storage and served through Cache, so price and stock freshness depend on rebuilds, and only cart and checkout reach the commerce API.
• Server-rendered headless commerce storefront: for catalogs with frequent price and stock changes or prices per region, where functions render pages with a framework such as Next.js and call the commerce API. Pages render on request, so the commerce API is in the request and failure flows, and freshness is a caching decision instead of a rebuild.

Configure the catalog cache

The catalog cache is a cache setting and the rule that applies it. The rule matches the catalog paths only for visitors without a session, so a signed-in visitor never receives a shared copy.

The cache setting uses two values. Max Age is 600 seconds: the purge configured below refreshes a changed page at once, so Max Age only bounds how long a page stays stale when a purge is missed. The browser cache is overridden to 0 seconds, because a copy in the visitor’s browser cannot be purged, and a stale price would stay there until it expires.

Catalog and product pages requested without a session cookie are cached for 600 seconds, and browsers revalidate them on every visit. A new rule takes a few minutes to propagate.

Configure the bypass for cart, checkout, and sessions

The bypass rule sends every per-visitor request to the store. It matches the cart, checkout, and account paths, and any request that carries the session cookie, so a visitor who added an item to the cart also bypasses the cache on catalog pages. The rule carries Forward Cookies as well, so the session cookie the store sets reaches the visitor. Nothing this rule matches is cached, so no visitor can receive another visitor’s cookie.

1. A request that carries the session_id cookie bypasses the cache, whatever its path.
2. A request without the cookie bypasses the cache on /cart, /checkout, and /account.
3. A request without the cookie on /products/ or /category/ takes the storefront-catalog cache setting.
4. Any other path is left to the application’s other rules.

The rule joins two procedures of Configure cache policies for an application, Bypass the cache for a path and Forward cookies from the origin to the user, in one rule with the store’s four criteria joined by Or. The guide’s denylist cache setting is left out, because nothing this rule matches is cached:

Cart, checkout, and account requests, and every request with a session, reach the store, and Azion stores none of their responses. A new rule takes a few minutes to propagate.

Configure purge on catalog changes

A changed product page is refreshed by a purge that the commerce platform sends when the product is saved. The call goes in the code the platform runs when a product is saved, and it authenticates with the personal token.

1. An admin saves a product, and the platform runs its save code.
2. The save code sends a URL purge for the product page and its category page, and a wildcard purge for the images when they changed.
3. Azion removes both pages from the cache once the purge propagates.
4. The next request for each page reaches the store, and the new version is cached.

The save code sends the purges that Purge pages when the origin publishes a change describes, with the store’s values:

• On every save, a URL purge for the product page and the category pages that list it. For the example product, the body of POST /v4/workspace/purge/url is:

  {"items":["https://www.example.com/products/blue-shirt","https://www.example.com/category/shirts"],"layer":"cache"}

• Only when the save changes the product’s images, a wildcard purge for every size and format of them. Azion accepts 2,000 wildcard purge requests in a 24-hour interval, so a wildcard on every save of a large catalog can reach that bound. The body of POST /v4/workspace/purge/wildcard is:

  {"items":["www.example.com/media/blue-shirt*"]}

Each call answers 201 with state set to executed. The product page, its category page, and any changed images leave the cache, and the next request for each one fetches the new version from the store. To confirm a purge completed, find it in the purge history, as the guide shows.

Verify the setup

Each check sends a request with the Pragma: azion-debug-cache header, which makes the response carry the x-cache header. For how to read it, refer to Check the cache status of a response.

• Catalog pages answer from cache. Request a product page twice without a cookie:

  curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/products/blue-shirt

  The second response carries x-cache: HIT. The first can carry MISS, while Azion fetches the page from the store.

• The cart never comes from cache. Request the cart:

  curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/cart

  The response carries x-cache: BYPASS.

• A visitor with a session never gets a shared catalog page. Request a product page with the session cookie:

  curl -sI -H "Pragma: azion-debug-cache" -H "Cookie: session_id=test" https://www.example.com/products/blue-shirt

  The response carries x-cache: BYPASS.

• A product change reaches the page. Send the purge for /products/blue-shirt, wait for it to appear in the purge history, and request the page again. The response carries x-cache: MISS, and the request after it carries HIT.

• Product images are processed. Request an image with an ims query string, such as https://www.example.com/media/blue-shirt.jpg?ims=400x. The response carries x-ims: Enabled.

A rule that seems to have no effect may still be propagating. When it persists after a few minutes, turn on Debug Rules to see which rules ran on the request.

Measuring results

Best practices

• Exclude sessions with a criterion, not with cookie variation. Varying the catalog cache key by session_id stores one copy per visitor, because the cookie is unique per visitor. The does not exist criterion keeps a single shared copy for every visitor without a session. For cookie variation and its cost, refer to Applications best practices.
• Never put Forward Cookies on a rule that caches. On a cached response, Forward Cookies can hand one visitor the Set-Cookie of another visitor’s session. On this page it sits only on the bypass rule, where nothing is cached.
• Purge on change instead of shortening Max Age. A short Max Age sends more catalog requests to the store and still leaves a stale window. The purge refreshes the page when it changes, and Max Age stays a safety bound for a missed purge.
• Use Bypass Cache for the cart, not a Max Age of 0. A Max Age of 0 merges simultaneous requests for one path into one origin request, and two visitors who load their carts at the same moment need different answers. For the difference between the two, refer to Cache variation.

Guides in this use case