Choose a version:

Header

The header area appears at the top of the checkout page, directly below the store logo and navigation. Extensions in this area add high-visibility content to the checkout experience that buyers see immediately on page load.

Anchor to Use casesUse cases

Sitewide promotion banners: Display time-limited offers like free shipping thresholds or volume discounts based on the buyer's cart total.
Loyalty program status: Show the buyer's loyalty points and how many they'll earn from the current purchase, with account creation prompts for new customers.
Discount code automation: Detect when a buyer qualifies for an automatic discount and apply it, displaying a confirmation banner with the savings amount.
Geo-targeted messaging: Display region-specific content like customs notices for international orders or currency conversion reminders based on the buyer's location.

Anchor to Header targetHeader target

Use this static extension target to extend the area directly below the checkout header. This target supports the full checkout component set, including form fields, banners, images, and interactive elements. The examples demonstrate using API methods for cart mutations and API properties for reading checkout state.

Anchor to Checkout header ,[object Object]Checkout header target

purchase.checkout.header.render-after

Adds persistent content directly below the checkout header. Like all checkout targets, this target has write access through API methods for cart lines, discount codes, gift cards, notes, attributes, metafields, and shipping address changes.

Extensions also have read access through API properties to shop information, buyer identity, cost breakdowns, cart lines, delivery groups, discount codes, localization, and other checkout state.

Support

Components (55)

APIs (24)

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

const FREE_SHIPPING_THRESHOLD = 75;

function Extension() {

const total = Number(

shopify.cost.totalAmount.value.amount,

);

const remaining = FREE_SHIPPING_THRESHOLD - total;

if (remaining <= 0) {

return (

<s-banner tone="success">

You've qualified for free shipping!

</s-banner>

);

}

return (

<s-banner>

Add ${remaining.toFixed(2)} more for free

shipping.

</s-banner>

);

}

Examples

Description

Create a header extension that calculates the gap between the buyer's cart total and a free shipping threshold, then displays a promotional banner with the remaining amount.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

const FREE_SHIPPING_THRESHOLD = 75;

function Extension() {
  const total = Number(
    shopify.cost.totalAmount.value.amount,
  );
  const remaining = FREE_SHIPPING_THRESHOLD - total;

  if (remaining <= 0) {
    return (
      <s-banner tone="success">
        You've qualified for free shipping!
      </s-banner>
    );
  }

  return (
    <s-banner>
      Add ${remaining.toFixed(2)} more for free
      shipping.
    </s-banner>
  );
}

Description

Detect returning customers and offer a one-click discount. This example checks `shopify.buyerIdentity` for a logged-in customer and uses `shopify.applyDiscountCodeChange` to apply a code.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [applied, setApplied] = useState(false);
  const customer =
    shopify.buyerIdentity?.customer.value;
  const canUpdate =
    shopify.instructions.value.discounts
      .canUpdateDiscountCodes;
  const existingCodes =
    shopify.discountCodes.value;

  if (
    !customer ||
    !canUpdate ||
    applied ||
    existingCodes.length > 0
  ) {
    return null;
  }

  async function applyDiscount() {
    const result =
      await shopify.applyDiscountCodeChange({
        type: 'addDiscountCode',
        code: 'WELCOME_BACK_10',
      });
    if (result.type === 'success') {
      setApplied(true);
    }
  }

  const name =
    customer.fullName ?? 'valued customer';

  return (
    <s-banner tone="info">
      <s-stack gap="base">
        <s-text>
          Welcome back, {name}! As a returning
          customer, you're eligible for 10% off.
        </s-text>
        <s-button onClick={applyDiscount}>
          Apply 10% discount
        </s-button>
      </s-stack>
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Reserve space for dynamic content: Layout shifts are highly visible in the header. If you load data asynchronously, use a skeleton paragraph or spinner to hold space while content loads.

Was this page helpful?