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

# Show a Maintenance Page

> Options for showing shoppers a maintenance page during a go-live, cutover, or planned outage: a Kibo-managed edge page, a maintenance flag in a headless storefront, or a core theme override.

A maintenance page tells shoppers that your storefront is temporarily unavailable and keeps them from browsing or placing orders while you work. Common reasons to show one:

* A go-live or cutover, when you want to test the new site before shoppers can reach it.
* A planned outage, such as a back-end system upgrade that stops orders from flowing.
* A data migration or catalog load that leaves the site in an inconsistent state for a while.

The Kibo platform does not have a single maintenance mode setting. Choose one of the options below based on how your storefront is built and whether the storefront itself will be running during the window.

| Option | Use it when | Who turns it on and off |
| - | - | - |
| [Edge maintenance page](#option-1-request-an-edge-maintenance-page-from-kibo-support) | Kibo serves your storefront domain, or the storefront itself will be down during the window | Kibo, at the times in your Support request |
| [Headless storefront flag](#option-2-add-a-maintenance-flag-to-a-headless-storefront) | You run a headless storefront, such as a Next.js app | Your team |
| [Core theme override](#option-3-override-the-core-theme) | Your storefront still runs on a Kibo core theme | Your team |

## Option 1: Request an Edge Maintenance Page from Kibo Support

For storefront domains that Kibo serves, Kibo can show a maintenance page in front of your storefront, at the network edge. Shoppers get the maintenance page before their request reaches your storefront, so the page keeps working even when the storefront itself is unavailable. Kibo uses this approach during platform cutovers and go-lives.

When the edge page is on:

* Every request to the domains you list gets the maintenance page.
* The response is HTTP `503 Service Unavailable` with a `Retry-After` header, so search engines treat the outage as temporary.
* The page is not cached, so shoppers see your live site again as soon as the page is removed.
* Kibo can let your team through to the real site during the window from IP addresses you provide, so you can test before you open the site to shoppers.

### Request the Page

[Open a Support case](https://help.kibocommerce.com/) as early as you can before the window. Include:

* Your tenant ID and site ID.
* Every storefront domain that should show the page, for example both `www.example.com` and `example.com`.
* The start and end time of the window, with the time zone.
* The page to show. Kibo can show a generic "under maintenance" page. If you want your own branding, send a self-contained HTML file or the URL of a maintenance page you host. If you send a URL, shoppers are redirected to it instead of seeing a page at your storefront address.
* The IP addresses, if any, that should bypass the page so your team can test.
* A contact who can confirm when the page should come down.

### Remove the Page

Kibo removes the page at the end time in your request. To bring your site back earlier or keep the page up longer, update your Support case or open a new one and say when the page should come down.

> [!NOTE]
>
> The edge page only covers domains whose traffic Kibo serves. If your storefront is hosted outside Kibo, for example a headless storefront on your own hosting provider, use [Option 2](#option-2-add-a-maintenance-flag-to-a-headless-storefront) or your hosting provider's maintenance feature instead.

## Option 2: Add a Maintenance Flag to a Headless Storefront

In a headless storefront, the maintenance page belongs to your front-end application. A common pattern is a flag that, when set, makes the app answer every page request with a maintenance page and a `503` status, while letting your own team through.

The example below is Next.js middleware. It reads the flag from an environment variable, lets through requests from allowlisted IP addresses or with a preview cookie, and returns a small maintenance page for everyone else.

```ts middleware.ts theme={null}
import { NextRequest, NextResponse } from 'next/server';

const MAINTENANCE_HTML = `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="robots" content="noindex">
    <title>Down for maintenance</title>
  </head>
  <body>
    <h1>We'll be back soon</h1>
    <p>Our store is down for scheduled maintenance. Please check back shortly.</p>
  </body>
</html>`;

export function middleware(request: NextRequest) {
  if (process.env.MAINTENANCE_MODE !== 'true') {
    return NextResponse.next();
  }

  // Let your team test the live site during the window.
  const allowedIps = (process.env.MAINTENANCE_ALLOW_IPS ?? '').split(',').map((ip) => ip.trim());
  const clientIp = request.headers.get('x-forwarded-for')?.split(',')[0].trim() ?? '';
  const previewCookie = request.cookies.get('maintenance_bypass')?.value;

  if (
    allowedIps.includes(clientIp) ||
    (previewCookie && previewCookie === process.env.MAINTENANCE_BYPASS_TOKEN)
  ) {
    return NextResponse.next();
  }

  return new NextResponse(MAINTENANCE_HTML, {
    status: 503,
    headers: {
      'Content-Type': 'text/html; charset=utf-8',
      'Retry-After': '3600',
      'Cache-Control': 'no-store',
    },
  });
}

export const config = {
  // Skip Next.js build assets and static files.
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

To use the pattern:

1. Add the middleware to your storefront and deploy it with `MAINTENANCE_MODE` unset or set to `false`.
2. To start the window, set `MAINTENANCE_MODE=true`. To let your team in, set `MAINTENANCE_ALLOW_IPS` to a comma-separated list of IP addresses, or set `MAINTENANCE_BYPASS_TOKEN` and have testers add a `maintenance_bypass` cookie with that value.
3. To end the window, set `MAINTENANCE_MODE=false`.

Keep these points in mind:

* **Changing an environment variable may need a redeploy.** On many hosting providers, a new environment variable value only takes effect after the next deployment. If you need to switch maintenance mode on and off without a deploy, read the flag from a source your app can change at runtime instead, such as your hosting provider's edge configuration store or a record in a Kibo [entity list](https://docs.kibocommerce.com/developer-guides/entities.md). Cache the value for a short time so the check does not add an API call to every request.
* **Check how your host reports the client IP.** The example reads the first address in `x-forwarded-for`. Confirm which header your hosting provider sets before you rely on the IP allowlist.
* **Keep API routes in mind.** The matcher above also covers your app's API routes. If a payment provider or other system calls your storefront's API routes during the window, exclude those paths from the matcher.

## Option 3: Override the Core Theme

If your storefront runs on a Kibo core theme, you can show a maintenance page from the theme. The storefront must be running for this option to work, so it does not help during an outage of the storefront itself.

* **Use a theme setting as the flag.** Add a setting such as `maintenanceMode` to your theme's settings, then add a condition to the page template (`page.hypr`) that renders a maintenance layout instead of the normal page when `themeSettings.maintenanceMode` is on. You can then switch the page on and off from the theme settings in Admin.
* **Use a separate maintenance theme.** Build a theme whose page template always renders the maintenance layout, and apply it for the window. Apply your regular theme again to end the window. See [Preview and Apply Themes](https://docs.kibocommerce.com/pages/preview-and-apply-themes.md).

Theme changes are cached, so the page may take several minutes to appear or disappear after you change the setting or the applied theme. Clear the theme cache from the Themes grid if you need the change to take effect sooner, and avoid doing so during peak trading hours.

A theme override renders the maintenance page through the normal page pipeline, so it does not return a `503` status. For a window longer than a few hours, or when search ranking matters, request the [edge maintenance page](#option-1-request-an-edge-maintenance-page-from-kibo-support) instead.

## Protect Your Search Rankings

Search engines treat a maintenance page differently depending on the HTTP status code it returns.

* **Return `503 Service Unavailable`.** A `503` tells crawlers the outage is temporary, so they keep your pages in their index and come back later.
* **Send a `Retry-After` header.** The header tells crawlers when to try again, either as a number of seconds (`Retry-After: 3600`) or as an HTTP date.
* **Don't return `200 OK` for the maintenance page.** If crawlers get a `200`, they can index the maintenance page in place of your real pages.
* **Don't redirect every URL to a maintenance URL for long.** A redirect to one page that returns `200` has the same effect as serving the maintenance page with `200`.
* **Keep windows short.** If crawlers keep getting a `503` for an extended period, typically more than a day or two, they may start to drop pages from their index.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.