Choose a version:

Navigation

Checkout presents buyers with an action button at the end of each section. Use this target to add UI before those buttons, giving you a place to collect marketing consent, capture gift notes, or show cart-based messages.

Shopify's checkout action buttons — such as Continue to payment and Pay now — can't be modified by any extension. Labels, disabled states, and appearance are controlled by Shopify.

This target doesn't render when Shop Pay is the active checkout method. During Apple Pay and Google Pay sessions, the target renders but cart mutation APIs such as applyNoteChange and applyMetafieldChange return error results.

Anchor to Use casesUse cases

Email and SMS marketing opt-in: Collect buyer consent for email or SMS marketing before checkout completes.
Gift notes: Let buyers add a personalized gift message to their order.
Cart messaging: Show contextual messages based on cart contents, such as a free shipping threshold or a discount code.
Reward points: Fetch the buyer's reward points balance from your backend and display how many points the current order will earn.

Anchor to Navigation targetNavigation target

Use this target to render UI before the action buttons on each checkout section. The examples below demonstrate note and metafield writes, the two most common write operations at this target.

Anchor to Render before checkout actions ,[object Object]Render before checkout actions target

purchase.checkout.actions.render-before

Renders before the action button on each checkout step, including information, shipping, payment, and review. Read access to cart contents, buyer identity, delivery details, and cost is available.

Write operations are available through the Note API and Metafields API. Use cart instructions to check which mutations are available before calling them.

Support

Components (55)

APIs (24)

Examples

jsx

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

import {render} from 'preact';

export default function extension() {

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

}

function Extension() {

async function onCheckboxChange(event) {

const isChecked = event.currentTarget.checked;

if (!shopify.instructions.value.notes.canUpdateNote) {

return;

}

const result = await shopify.applyNoteChange(

isChecked

? {type: 'updateNote', note: 'This is a gift order'}

: {type: 'removeNote'},

);

if (result.type === 'error') {

event.currentTarget.checked = !isChecked;

}

return (

<s-checkbox

onChange={onCheckboxChange}

label="Add a gift message to my order"

);

}

Examples

Description

Let buyers attach a gift message to their order with a checkbox before the action button. This example checks `canUpdateNote` through cart instructions, renders a checkbox, and applies a note change when the buyer opts in.

jsx

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

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

function Extension() {
  async function onCheckboxChange(event) {
    const isChecked = event.currentTarget.checked;
    if (!shopify.instructions.value.notes.canUpdateNote) {
      return;
    }
    const result = await shopify.applyNoteChange(
      isChecked
        ? {type: 'updateNote', note: 'This is a gift order'}
        : {type: 'removeNote'},
    );
    if (result.type === 'error') {
      event.currentTarget.checked = !isChecked;
    }
  }

  return (
    <s-checkbox
      onChange={onCheckboxChange}
      label="Add a gift message to my order"
    />
  );
}

Description

Collect buyer consent for email marketing and store it as a cart metafield. This example checks `canSetCartMetafields` and `canDeleteCartMetafield` through cart instructions and uses `MetafieldUpdateCartChange` to write the opt-in status.

jsx

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

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

function Extension() {
  async function onCheckboxChange(event) {
    const isChecked = event.currentTarget.checked;
    const {metafields} = shopify.instructions.value;
    if (isChecked && !metafields.canSetCartMetafields) return;
    if (!isChecked && !metafields.canDeleteCartMetafield) return;

    const result = isChecked
      ? await shopify.applyMetafieldChange({
          type: 'updateCartMetafield',
          metafield: {
            namespace: '$app:marketing',
            key: 'email_opt_in',
            value: 'true',
            type: 'single_line_text_field',
          },
        })
      : await shopify.applyMetafieldChange({
          type: 'removeCartMetafield',
          namespace: '$app:marketing',
          key: 'email_opt_in',
        });

    if (result.type === 'error') {
      event.currentTarget.checked = !isChecked;
    }
  }

  return (
    <s-checkbox
      onChange={onCheckboxChange}
      label="Send me emails about new products and promotions"
    />
  );
}

Anchor to Best practicesBest practices

Check note permissions before writing: Use shopify.instructions.value.notes.canUpdateNote before calling applyNoteChange. When the instruction is false, the method returns an error result instead of applying the change.
Check metafield write permissions: Use shopify.instructions.value.metafields.canSetCartMetafields before calling applyMetafieldChange. When the instruction is false, the method returns an error result instead of applying the change.
Revert UI state on failure: Check the mutation's return value for {type: 'error'} and revert the UI element to its previous state. Leaving a checkbox checked after a failed mutation misleads buyers into thinking their input was saved.
Keep extensions concise: Multiple extensions at this target stack vertically before the action button. Keep each extension's output brief to avoid pushing the button below the visible area.
Render conditionally to target a specific section: This target renders before the action button on every checkout section. Use conditional logic based on checkout state to limit your content to a specific section.
Use buyerJourney.intercept() to block navigation: Rendering at this target doesn't intercept or block the buyer from advancing. To prevent navigation until a condition is met, use buyerJourney.intercept(), which is available from any checkout extension target.

Was this page helpful?