Show a Maintenance Page

• 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.

​

Option 1: Request an Edge Maintenance Page from Kibo Support

• 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

• 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

​

Option 2: Add a Maintenance Flag to a Headless Storefront

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).*)'],
};

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.

• 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. 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

• 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.

​

Protect Your Search Rankings

• 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.