Traditionally, additional scripts were commonly used to display cart attributes on the thank you page of Shopify stores. However, this method is now deprecated, and the use of Checkout Extensibility is recommended.
Checkout Extensibility upgrade guide
To display cart attributes on the thank you page or order status page using Checkout Extensibility, the process is slightly more complex than the traditional method, but can be implemented with the following steps:
- Create a custom app using Checkout UI extensions
- Create a UI component to output cart attribute values
- Modify the configuration file
- Launch the custom app in a local environment
- Deploy the custom app
1. Create a Custom App Using Checkout UI Extensions
Checkout Extensibility offers several features for customization purposes. In this case, we'll use Checkout UI extensions.
Checkout UI extensions is a feature for extending the UI of the checkout page, allowing you to display components on the thank you page or order status page. Previously only available for Shopify Plus plan, it's now accessible for Basic plan and above.
There are restrictions on the scope of Checkout UI extensions depending on the plan.
Details are provided in the Summary section.
Set up the custom app development environment with an Extension-only app. If you already have a custom app, you can start from the generate extension step.
An Extension-only app is an app that doesn't have an app screen in the Shopify admin panel and is specialized for extensions. The entire extension app is hosted on Shopify, so there's no need to prepare separate infrastructure for the app. You can develop it with a feeling similar to CLI theme building.
This guide assumes the use of Shopify CLI. If you're new to it, please check the Shopify CLI official documentation for installation instructions.
Use the following command to initialize the custom app:
pnpm create @shopify/app
Answer the prompts to set up your project name, installation store, etc. We'll proceed with a TypeScript environment here.
Once the project is created, navigate to the target directory and run:
pnpm shopify app generate extension
When asked which type of extension to create, select Checkout UI.
Name your extension and initialize it. We'll proceed with a React TypeScript environment.
Necessary files should now be generated in the extensions directory.
2. Create a UI Component to Output Cart Attribute Values
Once the custom app development environment is set up, create a UI component to output cart attribute values.
Prerequisites
To retrieve cart attribute values, you need to implement a form using cart attributes on the cart page. Adjust the attribute names according to your expected cart attributes.
Let's implement an example where delivery date and time information is managed by cart attributes.
We assume the cart attribute names are set as follows:
-
delivery_date: Desired delivery date -
delivery_time: Desired delivery time
This article doesn't cover how to set up cart attributes in detail, but please refer to the following document to set up a form on the cart page:
https://shopify.dev/docs/api/liquid/objects/cart#cart-attributes
Open the Checkout.tsx file and edit it as follows:
import {
Heading,
BlockStack,
Text,
useTranslate,
useAttributeValues,
reactExtension,
} from "@shopify/ui-extensions-react/checkout";
export default reactExtension("purchase.thank-you.block.render", () => (
<Extension />
));
function Extension() {
const translate = useTranslate();
const [delivery_date, delivery_time] = useAttributeValues([
"delivery_date",
"delivery_time",
]);
return (
<BlockStack
padding="tight"
border="base"
cornerRadius="base"
background="base"
>
<Heading>{translate("title")}</Heading>
<Text size="base">
{translate("deliveryDate")}: {delivery_date || "Not specified"}
</Text>
<Text size="base">
{translate("deliveryTime")}: {delivery_time || "Not specified"}
</Text>
</BlockStack>
);
}
Components
The following components are used, but feel free to change them as needed:
- Heading: Output heading
- Text: Output text
- BlockStack: Stack elements vertically
https://shopify.dev/docs/api/checkout-ui-extensions/2023-04/components
React Hooks
The following hooks are used:
- useTranslate (optional): Multilingual support
- useAttributeValues: Retrieve attribute values
The useTranslate hook is used for multilingual support, so you can omit it if not needed. If you use it, modify the file information in the locales folder as follows:
// extensions/extension-name/locales/en.default.json
{
"title": "Delivery Date and Time",
"deliveryDate": "Delivery Date",
"deliveryTime": "Delivery Time"
}
useAttributeValues is necessary to retrieve cart attribute values. Use it by specifying attribute names as follows:
const [delivery_date, delivery_time] = useAttributeValues([
"delivery_date",
"delivery_time",
]);
reactExtension is a required function for outputting components. Specify the target as the first argument. The target indicates where the extension will be applied.
Here, we specify purchase.thank-you.block.render to output on the thank you page.
3. Modify the Configuration File
Open the shopify.extension.toml file and modify the target. Note that you need to register the target in the toml file as well as in the component.
# extensions/extension-name/shopify.extension.toml
[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.thank-you.block.render"
4. Launch the Custom App in a Local Environment
Launch the custom app in a local environment:
pnpm dev
After launching, press p to open the preview and confirm that the cart attribute values are displayed on the thank you page.
› Press p │ preview in your browser
You can also display cart attribute values on the order status page by adding an extension and changing the target.
export default reactExtension(
"customer-account.order-status.block.render",
() => <Extension />
);
[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "customer-account.order-status.block.render"
5. Deploy the Custom App
Once development in the local environment is complete, deploy the custom app:
pnpm run deploy
Confirm that the app is reflected in the "App Management" section of the Partner Dashboard. Install the app in your store and check it. A customization path is set up in the "Checkout" section of the store admin panel.
Add the app block and confirm that the elements are displayed.
Note
The components available in Checkout UI extensions are strictly limited. Therefore, you cannot use custom UI components or HTML tags.
Even if you write unavailable tags and errors occur, no error messages will be displayed on the front-end screen. It's recommended to check the terminal for error messages regularly.
Summary
We've introduced how to display cart attribute values using Checkout UI extensions. By using Checkout Extensibility, you can achieve safer and more flexible customization.
However, the applicable range differs depending on the plan, so please check the available range before proceeding with implementation. The content introduced in this article is available for Basic plans and above. (As of August 16, 2024)
https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations
Top comments (0)