Purging overview
The documentation only applies to instances deployed on Alokai@Edge.
Purging removes cached content from the CDN so that the next request is served fresh from your origin. You may need to purge when content is updated, incorrect, or when a new version of your storefront is deployed.
Alokai provides three purging methods, each suited to different scenarios. Choose the narrowest method that covers your change — targeted purging keeps your cache hit ratio high and minimizes origin load.
Purging methods
| Purge URL | Purge by keys | Purge all | |
|---|---|---|---|
| Scope | A single cached object identified by its exact URL. | All cached objects tagged with one or more keys. | Every cached object across the instance. |
| Precision | Highest — one object at a time. | High — targets a logical group of objects (e.g., all pages for a product). | None — everything is cleared. |
| Soft purge | Yes — can mark the object as stale instead of removing it. | Yes — can mark tagged objects as stale instead of removing them. | No — always a hard purge. |
| Origin impact | Minimal — only one extra origin request. | Low to moderate — only purged objects are re-fetched. | High — all traffic hits the origin until the cache rebuilds. |
| Requires app changes | No. | Partially yes — for keys other than host name your application must set the Surrogate-Key response header. | No. |
| Best for | Fixing a single page or asset. | Routine content updates that affect multiple pages. | Major deployments, global config changes, incident recovery. |
Choosing the right method
Start with the most targeted option and escalate only if needed.
A single page or asset changed — Use purge URL. Enter the exact URL and the CDN invalidates that one object. Quick, precise, and zero risk of over-purging.
A product, category, or content entity changed — Use purge by keys. If your application tags responses with surrogate keys (e.g., product-123, category-shoes), you can purge every page that references that entity in a single operation — without knowing all the individual URLs involved.
A specific domain needs a full refresh — Use purge by keys with the domain as the key. Alokai automatically adds the request's browser domain (e.g., store.example.com) as a surrogate key to every response, so you can clear an entire storefront without affecting other domains on the same instance.
Everything needs to go — Use purge all. This is the right choice after a major deployment or global configuration change, but it drops your cache hit ratio to zero and spikes origin traffic. Use sparingly.
How purging relates to caching rules
Purging controls when cached content is removed. Your caching rules control what gets cached and how long it stays fresh. The two work together:
- TTL (time-to-live) determines how long content is served from cache before it naturally expires. Short TTLs reduce the need for manual purging but increase origin traffic.
- Cache key configuration (query parameters, cookies) determines how many variants of a URL are cached. This directly affects purge URL — you need to match the exact cache key, including any parameters in your allow list.
- Stale-if-error allows the CDN to serve stale content when the origin returns an error. Soft purge works hand-in-hand with this — stale-marked objects can still be served during origin issues.
A well-designed caching and purging strategy uses reasonable TTLs as a baseline, surrogate keys for targeted invalidation of content changes, and purge all only as a last resort.
Further reading
- Purge URL — Remove a single cached object by its exact URL.
- Purge by keys — Remove groups of cached objects using surrogate keys.
- Purge all — Remove every cached object across the instance.
- Caching rules — Configure what gets cached and how the cache key is constructed.
- Fastly purging documentation — Technical reference for the underlying CDN purging mechanisms.