Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Shipping

The shipping step is where buyers enter a delivery address and select a shipping method. Use shipping targets to add address validation, delivery date pickers, shipping insurance offers, and messages with delivery information.

Anchor to Use casesUse cases

Delivery date selection: Display a date picker under a specific shipping option so buyers can choose their preferred delivery date.
Shipping insurance: Offer shipping protection for high-value orders.
Delivery-region restrictions: Display a notice if the buyer's address is outside the allowed delivery region.
Carbon-neutral shipping: Highlight eco-friendly shipping options or offer a carbon offset add-on after the buyer selects a method.
Split shipping guidance: When an order splits into multiple shipments, display messaging that explains why items are shipping separately.

Anchor to Delivery address targetsDelivery address targets

The render-before and render-after delivery address targets position content around the shipping address form. These targets have read access through API properties and write access through API methods.

Anchor to Render before delivery address ,[object Object]Render before delivery address target

purchase.checkout.delivery-address.render-before

This target renders between the shipping address header and the address form fields. Use this target to display address-related guidance or validation messaging before the buyer enters their address.

Read access to cart contents, buyer identity, and delivery details is available through API properties. The buyer's current shipping address is available through useShippingAddress().

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Banner,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.delivery-address.render-before',

() => <Extension />,

);

function Extension() {

return (

Include your apartment or unit number

for accurate delivery.

</Banner>

);

}

Examples

Description

Show a reminder before the address form asking buyers to enter their full address, including apartment or unit number, for accurate delivery.

React

import {
  reactExtension,
  Banner,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.delivery-address.render-before',
  () => <Extension />,
);

function Extension() {
  return (
    <Banner>
      Include your apartment or unit number
      for accurate delivery.
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.delivery-address.render-before',
  (root) => {
    root.appendChild(
      root.createComponent(
        Banner,
        {},
        'Include your apartment or unit number for accurate delivery.',
      ),
    );
  },
);

Anchor to Render after delivery address ,[object Object]Render after delivery address target

purchase.checkout.delivery-address.render-after

This target renders after the shipping address form fields. Use this target to display post-address content such as delivery notes or address verification results.

Read access to cart contents, buyer identity, and delivery details is available through API properties. The buyer's current shipping address is available through useShippingAddress().

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

TextField,

useApplyMetafieldsChange,

useInstructions,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.delivery-address.render-after',

() => <Extension />,

);

function Extension() {

const applyMetafieldChange =

useApplyMetafieldsChange();

const {metafields} = useInstructions();

async function onChange(value) {

if (!metafields.canSetCartMetafields) {

return;

}

await applyMetafieldChange({

type: 'updateCartMetafield',

metafield: {

namespace: '$app:delivery',

key: 'instructions',

value,

type: 'single_line_text_field',

});

}

return (

<TextField

label="Delivery instructions (optional)"

onChange={onChange}

);

}

Examples

Description

Display a text field after the address form where buyers can add special delivery instructions. This example stores the instructions as a cart metafield.

React

import {
  reactExtension,
  TextField,
  useApplyMetafieldsChange,
  useInstructions,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.delivery-address.render-after',
  () => <Extension />,
);

function Extension() {
  const applyMetafieldChange =
    useApplyMetafieldsChange();
  const {metafields} = useInstructions();

  async function onChange(value) {
    if (!metafields.canSetCartMetafields) {
      return;
    }
    await applyMetafieldChange({
      type: 'updateCartMetafield',
      metafield: {
        namespace: '$app:delivery',
        key: 'instructions',
        value,
        type: 'single_line_text_field',
      },
    });
  }

  return (
    <TextField
      label="Delivery instructions (optional)"
      onChange={onChange}
    />
  );
}

TS

import {
  extension,
  TextField,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.delivery-address.render-after',
  (root, {instructions, applyMetafieldChange}) => {
    const {metafields} = instructions.current;

    if (!metafields.canSetCartMetafields) return;

    root.appendChild(
      root.createComponent(
        TextField,
        {
          label: 'Delivery instructions (optional)',
          async onChange(value: string) {
            await applyMetafieldChange({
              type: 'updateCartMetafield',
              metafield: {
                namespace: '$app:delivery',
                key: 'instructions',
                value,
                type: 'single_line_text_field',
              },
            });
          },
        },
      ),
    );
  },
);

Anchor to Shipping option list targetsShipping option list targets

The render-before and render-after shipping option list targets position content around the list of available shipping methods. For both targets, you can access the ShippingOptionsListApi using the useApi() hook. This API has two properties, target, which contains the delivery group, and deliverySelectionGroups, which contains information for split-shipping scenarios.

Anchor to Render before shipping options ,[object Object]Render before shipping options target

purchase.checkout.shipping-option-list.render-before

This target renders between the shipping method header and the list of shipping options. Use this target to display general shipping information or promotions that apply to all available methods.

Access the current delivery group through api.target and split shipping delivery selection groups through api.deliverySelectionGroups from useApi(). Subscribe to these values with useSubscription() to reactively update your extension. Read access to cart contents, buyer identity, and delivery details is available through API properties.

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Banner,

useApi,

useSubscription,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.shipping-option-list.render-before',

() => <Extension />,

);

function Extension() {

const api = useApi();

const target = useSubscription(api.target);

const deliveryGroups =

target?.deliveryGroups ?? [];

if (deliveryGroups.length <= 1) return null;

return (

Your order contains items that ship

separately. Select a shipping method for

each shipment.

</Banner>

);

}

Examples

Description

When the order requires multiple shipments, display a banner explaining the split. This example checks whether more than one delivery group exists and renders guidance for the buyer.

React

import {
  reactExtension,
  Banner,
  useApi,
  useSubscription,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-list.render-before',
  () => <Extension />,
);

function Extension() {
  const api = useApi();
  const target = useSubscription(api.target);
  const deliveryGroups =
    target?.deliveryGroups ?? [];

  if (deliveryGroups.length <= 1) return null;

  return (
    <Banner>
      Your order contains items that ship
      separately. Select a shipping method for
      each shipment.
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-list.render-before',
  (root, api) => {
    const deliveryGroups =
      api.target.current?.deliveryGroups ?? [];

    if (deliveryGroups.length <= 1) return;

    root.appendChild(
      root.createComponent(
        Banner,
        {},
        'Your order contains items that ship separately. Select a shipping method for each shipment.',
      ),
    );
  },
);

Anchor to Render after shipping options ,[object Object]Render after shipping options target

purchase.checkout.shipping-option-list.render-after

This target renders after the list of shipping options. Use this target to display supplementary information below the shipping methods, such as delivery disclaimers or estimated arrival date.

This target provides the same API access as render-before through the useApi() hook. Use api-target to read the delivery group and api-deliverySelectionGroups to access information about split-shipping groups. Read access to cart contents, buyer identity, and delivery details is available through API properties.

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Text,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.shipping-option-list.render-after',

() => <Extension />,

);

function Extension() {

return (

<Text>

Delivery estimates are calculated from

the shipping date and don't include

processing time.

</Text>

);

}

Examples

Description

Display a disclaimer about delivery estimates below the shipping options list. This example renders a text notice that applies to all available methods.

React

import {
  reactExtension,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-list.render-after',
  () => <Extension />,
);

function Extension() {
  return (
    <Text>
      Delivery estimates are calculated from
      the shipping date and don't include
      processing time.
    </Text>
  );
}

TS

import {
  extension,
  Text,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-list.render-after',
  (root) => {
    root.appendChild(
      root.createComponent(
        Text,
        {},
        "Delivery estimates are calculated from the shipping date and don't include processing time.",
      ),
    );
  },
);

Anchor to Shipping option item targetsShipping option item targets

The details.render and render-after shipping option item targets render for each individual shipping option in the list. Both provide access to the ShippingOptionItemApi, which includes target containing the shipping option details, isTargetSelected indicating whether the buyer has selected that option, and renderMode with layout information, accessed through useApi() and useSubscription().

Anchor to Render shipping option details ,[object Object]Render shipping option details target

purchase.checkout.shipping-option-item.details.render

For each option in the shipping option list, this target renders under the shipping method name. Use this target to display expanded details for a shipping method, such as a delivery date picker or additional cost breakdowns.

Access the shipping option through api.target, selection state through api.isTargetSelected, and layout context through api.renderMode from useApi(). Subscribe to these values with useSubscription() for reactive updates. Read access to cart contents, buyer identity, and delivery details is available through API properties.

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Text,

useApi,

useSubscription,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.shipping-option-item.details.render',

() => <Extension />,

);

function Extension() {

const api = useApi();

const isSelected = useSubscription(

api.isTargetSelected,

);

const option = useSubscription(api.target);

if (!isSelected) return null;

const estimate =

option.deliveryEstimate?.timeInTransit;

if (!estimate?.lower || !estimate?.upper)

return null;

const lowerDays = Math.round(

estimate.lower / 86400,

);

const upperDays = Math.round(

estimate.upper / 86400,

);

return (

<Text>

Estimated delivery: {lowerDays}–{upperDays}{' '}

days

</Text>

);

}

Examples

Description

Display a delivery date estimate when the buyer selects a shipping option. This example reads the target's delivery estimate and renders it only for the selected method.

React

import {
  reactExtension,
  Text,
  useApi,
  useSubscription,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-item.details.render',
  () => <Extension />,
);

function Extension() {
  const api = useApi();
  const isSelected = useSubscription(
    api.isTargetSelected,
  );
  const option = useSubscription(api.target);

  if (!isSelected) return null;

  const estimate =
    option.deliveryEstimate?.timeInTransit;
  if (!estimate?.lower || !estimate?.upper)
    return null;

  const lowerDays = Math.round(
    estimate.lower / 86400,
  );
  const upperDays = Math.round(
    estimate.upper / 86400,
  );

  return (
    <Text>
      Estimated delivery: {lowerDays}–{upperDays}{' '}
      days
    </Text>
  );
}

TS

import {
  extension,
  Text,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-item.details.render',
  (root, api) => {
    const text = root.createComponent(Text, {});
    let mounted = false;

    function update() {
      const isSelected =
        api.isTargetSelected.current;
      const option = api.target.current;

      if (!isSelected) {
        text.remove();
        mounted = false;
        return;
      }

      const estimate =
        option.deliveryEstimate?.timeInTransit;
      if (!estimate?.lower || !estimate?.upper) {
        text.remove();
        mounted = false;
        return;
      }

      const lowerDays = Math.round(
        estimate.lower / 86400,
      );
      const upperDays = Math.round(
        estimate.upper / 86400,
      );

      text.replaceChildren(
        `Estimated delivery: ${lowerDays}–${upperDays} days`,
      );

      if (!mounted) {
        root.appendChild(text);
        mounted = true;
      }
    }

    api.isTargetSelected.subscribe(update);
    api.target.subscribe(update);
    update();
  },
);

Anchor to Render after shipping option ,[object Object]Render after shipping option target

purchase.checkout.shipping-option-item.render-after

For each delivery option in the list, this target renders after the shipping method details. Use this target to display supplementary information about a shipping method, such as insurance offers or carrier information.

This target provides the same API access as details.render: the shipping option through api.target, selection state through api.isTargetSelected, and layout context through api.renderMode from useApi(). Read access to cart contents, buyer identity, and delivery details is available through API properties.

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Checkbox,

useApi,

useSubscription,

useApplyMetafieldsChange,

useInstructions,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.shipping-option-item.render-after',

() => <Extension />,

);

function Extension() {

const api = useApi();

const isSelected = useSubscription(

api.isTargetSelected,

);

const applyMetafieldChange =

useApplyMetafieldsChange();

const {metafields} = useInstructions();

if (!isSelected) return null;

async function onCheckboxChange(isChecked) {

if (!metafields.canSetCartMetafields) {

return;

}

if (isChecked) {

await applyMetafieldChange({

type: 'updateCartMetafield',

metafield: {

namespace: '$app:shipping',

key: 'insurance',

value: 'true',

type: 'single_line_text_field',

});

} else {

await applyMetafieldChange({

type: 'removeCartMetafield',

namespace: '$app:shipping',

key: 'insurance',

});

}

return (

Add shipping protection ($2.99)

</Checkbox>

);

}

Examples

Description

Display a shipping insurance opt-in checkbox after the selected shipping option. This example checks isTargetSelected and renders the offer only for the method the buyer has chosen.

React

import {
  reactExtension,
  Checkbox,
  useApi,
  useSubscription,
  useApplyMetafieldsChange,
  useInstructions,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-item.render-after',
  () => <Extension />,
);

function Extension() {
  const api = useApi();
  const isSelected = useSubscription(
    api.isTargetSelected,
  );
  const applyMetafieldChange =
    useApplyMetafieldsChange();
  const {metafields} = useInstructions();

  if (!isSelected) return null;

  async function onCheckboxChange(isChecked) {
    if (!metafields.canSetCartMetafields) {
      return;
    }
    if (isChecked) {
      await applyMetafieldChange({
        type: 'updateCartMetafield',
        metafield: {
          namespace: '$app:shipping',
          key: 'insurance',
          value: 'true',
          type: 'single_line_text_field',
        },
      });
    } else {
      await applyMetafieldChange({
        type: 'removeCartMetafield',
        namespace: '$app:shipping',
        key: 'insurance',
      });
    }
  }

  return (
    <Checkbox onChange={onCheckboxChange}>
      Add shipping protection ($2.99)
    </Checkbox>
  );
}

TS

import {
  extension,
  Checkbox,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-item.render-after',
  (root, api) => {
    if (!api.isTargetSelected.current) return;

    const {metafields} =
      api.instructions.current;
    if (!metafields.canSetCartMetafields) return;

    root.appendChild(
      root.createComponent(
        Checkbox,
        {
          async onChange(isChecked: boolean) {
            if (isChecked) {
              await api.applyMetafieldChange({
                type: 'updateCartMetafield',
                metafield: {
                  namespace: '$app:shipping',
                  key: 'insurance',
                  value: 'true',
                  type: 'single_line_text_field',
                },
              });
            } else {
              await api.applyMetafieldChange({
                type: 'removeCartMetafield',
                namespace: '$app:shipping',
                key: 'insurance',
              });
            }
          },
        },
        'Add shipping protection ($2.99)',
      ),
    );
  },
);

Anchor to Best practicesBest practices

Use isTargetSelected to limit per-option content: The item-level targets render for every shipping option. Show detailed content only for the selected option to keep the list easy to scan.
Account for split shipping: When the order has multiple delivery groups, the shipping option list targets render once per group. Use api.target from useApi() to read the current delivery group and display group-relevant content.

Anchor to LimitationsLimitations

Shipping data is read-only: Extensions can read shipping options and delivery groups but can't modify the shipping option list, reorder methods, or change shipping rates.
renderMode.overlay affects layout: When api.renderMode.overlay from useApi() is true, the item-level target renders in an overlay context rather than inline. Test your extension with both layout modes to confirm it displays correctly.

Was this page helpful?

Shipping

Anchor to Use casesUse cases

Anchor to Delivery address targetsDelivery address targets

Anchor to Render before delivery address ,[object Object]Render before delivery address target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Render after delivery address ,[object Object]Render after delivery address target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Shipping option list targetsShipping option list targets

Anchor to Render before shipping options ,[object Object]Render before shipping options target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Render after shipping options ,[object Object]Render after shipping options target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Shipping option item targetsShipping option item targets

Anchor to Render shipping option details ,[object Object]Render shipping option details target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Render after shipping option ,[object Object]Render after shipping option target

Supported components

Available APIs

Supported components

Available APIs

Anchor to Best practicesBest practices

Anchor to LimitationsLimitations