Skip to main content

purchase.checkout.header.render-after

Requires access to protected customer data for some properties.

A static extension target that is rendered below the header.

Tip

To prevent layout shifting, avoid dynamic data fetching & rendering in this target. If you need to render dynamic content, consider reserving space for your content while it is loading. See: Spinner, SkeletonText, or BlockSpacer.

Support
Components (55)
APIs (24)

Supported components

Available APIs

Anchor to checkoutapiCheckoutApi

The API object provided to this and other purchase.checkout extension targets.

Anchor to applyCartLinesChange
applyCartLinesChange
(change: ) => Promise<>
required

Adds, removes, or updates line items in the cart. The returned promise resolves when the change has been applied by the server, and the lines property updates with the new state.

Note

This method returns an error if the cart instruction lines.canAddCartLine is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to applyDiscountCodeChange
applyDiscountCodeChange
(change: ) => Promise<>
required

Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the discountCodes property updates with the new state.

Caution

> See security considerations if your extension retrieves discount codes through a network call.

Note

This method returns an error if the cart instruction discounts.canUpdateDiscountCodes is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to applyGiftCardChange
applyGiftCardChange
(change: ) => Promise<>
required

Adds or removes a gift card from the checkout. The returned promise resolves when the change has been applied by the server, and the appliedGiftCards property updates with the new state.

Caution

> See security considerations if your extension retrieves gift card codes through a network call.

Note

This method returns an error if the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to applyMetafieldChange
applyMetafieldChange
(change: ) => Promise<>
required

Creates, updates, or removes a cart metafield on the checkout. On success, the metafields property updates to reflect the change.

Cart metafields are copied to order metafields at order creation time if there's a matching order metafield definition with the cart to order copyable capability enabled.

Note

This method returns an error if the cart instruction metafields.canSetCartMetafields is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to applyNoteChange
applyNoteChange
(change: ) => Promise<>
required

Sets or removes the buyer's note on the checkout. On success, the note property updates to reflect the change.

Note

This method returns an error if the cart instruction notes.canUpdateNote is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to applyShippingAddressChange
applyShippingAddressChange
(change: ) => Promise<>

Updates the buyer's shipping address on the checkout. The provided fields are merged into the existing address without prompting the buyer. On success, the shippingAddress property updates to reflect the change.

Note

This method returns an error if the cart instruction delivery.canSelectCustomAddress is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Requires access to protected customer data.

Anchor to applyAttributeChange
applyAttributeChange
(change: ) => Promise<>
required

Updates or removes an attribute on the cart and checkout. On success, the attributes property updates to reflect the change.

Note

This method returns an error if the cart instruction attributes.canUpdateAttributes is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Deprecated

Use cart metafields instead.

Anchor to standardapiStandardApi

The base API object provided to this and other purchase.checkout and purchase.thank-you extension targets.

Anchor to analytics
analytics
required

Tracks custom events and sends visitor information to Web Pixels. Use publish() to emit events and visitor() to submit buyer contact details.

Anchor to appliedGiftCards
appliedGiftCards
<[]>
required

The gift cards that have been applied to the checkout. Each entry includes the last four characters of the gift card code, the amount used at checkout, and the card's remaining balance.

Anchor to applyTrackingConsentChange
applyTrackingConsentChange
required

Enables setting and updating customer privacy consent settings and tracking consent metafields.

Note

Requires the customer_privacy capability to be set to true.

Requires access to protected customer data.

Anchor to appMetafields
appMetafields
<[]>
required

The metafields requested in the shopify.extension.toml file. These metafields are updated when there's a change in the merchandise items being purchased by the customer.

App owned metafields are supported and are returned using the $app format. The fully qualified reserved namespace format such as app--{your-app-id}[--{optional-namespace}] isn't supported. See app owned metafields for more information.

Requires access to protected customer data.

Anchor to attributes
attributes
<[]>
required

The custom key-value attributes attached to the cart or checkout. These are set by the buyer or by an extension using applyAttributeChange(). The list is empty if no attributes have been added.

Anchor to availablePaymentOptions
availablePaymentOptions
<[]>
required

All payment options available to the buyer for this checkout, such as credit cards, wallets, and local payment methods. The list depends on the shop's payment configuration and the buyer's region.

Anchor to buyerJourney
buyerJourney
required

Provides details on the buyer's progression through the checkout and lets you intercept navigation to validate data before the buyer continues.

Refer to buyer journey examples for more information.

Anchor to checkoutSettings
checkoutSettings
<>
required

Settings applied to the buyer's checkout.

Anchor to checkoutToken
checkoutToken
< | undefined>
required

A stable ID that represents the current checkout.

The value is undefined when the checkout hasn't been created on the server yet.

Use this to correlate checkout sessions across your extension, web pixels, and backend systems.

This matches the data.checkout.token field in a checkout-related WebPixel event and the checkout_token field in the REST Admin API Order resource.

Anchor to cost
cost
required

The cost breakdown for the current checkout, including subtotal, shipping, tax, and total amounts. These values update as the buyer progresses through checkout and costs like shipping and tax are calculated.

Anchor to customerPrivacy
customerPrivacy
<>
required

Customer privacy consent settings and a flag denoting if consent has previously been collected.

Anchor to deliveryGroups
deliveryGroups
<[]>
required

The delivery groups for this checkout. Each group contains one or more cart lines and the available delivery options (shipping, pickup point, or pickup location) for those items.

Anchor to discountAllocations
discountAllocations
<[]>
required

The discount allocations applied to the entire cart, including automatic discounts, code-based discounts, and custom discounts from Shopify Functions. Each allocation indicates how much was discounted and how the discount was triggered.

Anchor to discountCodes
discountCodes
<[]>
required

The discount codes currently applied to the checkout. The list is empty if no discount codes have been applied. Use applyDiscountCodeChange() to add or remove codes.

Anchor to extension
extension
<Target>
required

Metadata about the running extension, including the current target, API version, capabilities, and editor context. Use this to conditionally render content based on where the extension is running.

Anchor to i18n
i18n
required

Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Use alongside localization to build fully localized extensions.

Anchor to instructions
instructions
<>
required

The cart instructions used to create the checkout and possibly limit extension capabilities.

These instructions should be checked before performing any actions that might be affected by them.

For example, if you intend to add a discount code via the applyDiscountCodeChange method, check discounts.canUpdateDiscountCodes to ensure it's supported in this checkout.

Caution

As of version 2024-07, UI extension code must check for instructions before calling select APIs in case those APIs aren't available. See the update guide for more information.

Anchor to lines
lines
<[]>
required

The list of line items the buyer intends to purchase. Each entry includes the merchandise, quantity, cost, and any custom attributes. Use applyCartLinesChange() to add, remove, or update line items.

Anchor to localization
localization
required

The buyer's language, country, currency, and timezone context. For formatting and translation helpers, use the i18n object instead.

Anchor to note
note
<string | undefined>
required

A note left by the customer to the merchant, either in their cart or during checkout.

The value is undefined if the buyer hasn't entered a note. Use this to display or react to order-level instructions such as delivery preferences or gift messages.

Anchor to query
query
<Data = unknown, Variables = Record<string, unknown>>(query: string, options?: { variables?: Variables; version?: ; }) => Promise<{ data?: Data; errors?: []; }>
required

The method used to query the Storefront GraphQL API with a prefetched token.

Refer to Storefront API access examples for more information.

Anchor to selectedPaymentOptions
selectedPaymentOptions
<[]>
required

The payment options the buyer has currently selected. This updates as the buyer changes their payment method. The array can contain multiple entries when the buyer splits payment across methods (for example, a gift card and a credit card).

Anchor to sessionToken
sessionToken
required

The session token providing a set of claims as a signed JSON Web Token (JWT).

The token has a TTL of five minutes.

If the previous token expires, this value reflects a new session token with a new signature and expiry.

Refer to session token examples for more information.

Anchor to settings
settings
<>
required

The settings matching the settings definition written in the shopify.extension.toml file.

Refer to settings examples for more information.

Note

When an extension is being installed in the editor, the settings are empty until a merchant sets a value. In that case, this object updates in real time as a merchant fills in the settings.

Anchor to shop
shop
required

The store where the checkout is taking place, including the shop name, storefront URL, .myshopify.com subdomain, and a globally-unique ID.

Anchor to storage
storage
required

Key-value storage that persists across page loads within the current checkout session. Data is shared across all activated extension targets of this extension.

Caution

Data persistence isn't guaranteed and storage is cleared when the buyer starts a new checkout.

Anchor to version
version
required

The renderer version being used for the extension.

Anchor to billingAddress
billingAddress
< | undefined>

The proposed customer billing address. The address updates when the field is committed (on change) rather than every keystroke. The property is available only if the extension has access to protected customer data. The subscribable value is undefined if the billing address hasn't been provided yet.

Requires access to protected customer data.

Anchor to buyerIdentity
buyerIdentity

Information about the buyer that's interacting with the checkout. The property is available only if the extension has access to protected customer data.

Requires access to protected customer data.

Anchor to localizedFields
localizedFields
<[]>

Additional region-specific fields required during checkout, such as tax identification numbers (Brazil's CPF/CNPJ) or customs credentials. The property is available only if the extension has access to protected customer data. The array is empty if the current checkout doesn't require any localized fields.

Anchor to shippingAddress
shippingAddress
< | undefined>

The proposed customer shipping address. During the information step, the address updates when the field is committed (on change) rather than every keystroke. The property is available only if the extension has access to protected customer data. When available, the subscribable value is undefined if delivery isn't required.

Requires access to protected customer data.

Anchor to extensionPoint
extensionPoint
Target
required

The identifier that specifies where in Shopify's UI your code is being injected. This is one of the targets you've included in your extension's configuration file.

Deprecated

Deprecated as of version 2023-07, use extension.target instead.

Examples

Preact

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

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

function Extension() {
return (
<s-stack gap="base">
<s-paragraph>
Shop name: {shopify.shop.name}
</s-paragraph>
<s-paragraph>
cost:{' '}
{shopify.cost.totalAmount.value.amount}
</s-paragraph>
</s-stack>
);
}

Anchor to relatedRelated

ReferenceAPIs
ReferenceComponents
ReferenceConfiguration
LearnTutorials
Was this page helpful?