# Welcome to Platter+ 👋

Platter+ is a Shopify app that helps merchants create and optimize checkout and post-purchase experiences, increasing both average order value (AOV) and conversion rates (CVR).

If you've never used Platter+ before, this is a great place to get started.

Our app is pretty easy to navigate, so we hope that you don't have to read too much of this knowledge base. But everyone has a question once in a while!

If you can't find what you're looking for here, have a request, or need to talk to a real human, feel free to email us directly at [hello@platter.co](mail:hello@platter.co)[.](mailto:platter.co)

***

## What is Platter+?

Platter+ is Shopify app that makes it easy for Shopify Plus merchants to increase Average Order Value (AOV) and guarantee a 5x ROI—all in just minutes.

{% tabs %}
{% tab title="With Platter+" %}

<figure><img src="/files/eyNKvpFZhfLDPwW7JNnH" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Without Platter+" %}

<figure><img src="/files/x1hvW2AGTAPSya3uVobs" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

**Maximize AOV with every order**

Generate more revenue with every transaction by optimizing your checkout. With Platter+, you can add upsells, cross-sells, and other powerful features to your checkout, increasing average order value and conversion rate with minimal effort.

**5x ROI Guarantee**

Our pricing is built to align with your success. You don’t pay until you see results, with a guarantee that Platter+ will deliver a minimum 5x return on investment. Plus, every month you can generate the first $1,250 for free.

**Easy setup in minutes**

Say goodbye to complex configurations or relying on developers. Platter+ is designed to be incredibly simple to set up and use—whether you're adding your first checkout extension or making optimizations during BFCM, you'll be up and running in no time.

***

With Platter+, you can focus on what matters: increasing revenue, improving profitability, and making your customers happy with a seamless checkout experience.

**Let’s get started.**


# Installing the app

How to install Platter+ on your Shopify store

This guide will walk you through the process of installing the Platter+ app on your Shopify store. It is a quick and easy process, and takes under 2 minutes!

### Step 1: Shopify App Store <a href="#h_eb9630b539" id="h_eb9630b539"></a>

Navigate to the Shopify App Store Using this [link](https://apps.shopify.com/platter-plus).&#x20;

<figure><img src="/files/DA1omxRHHQK7Y0LuX0VS" alt=""><figcaption></figcaption></figure>

### Step 2: Install Platter+ <a href="#h_f433348138" id="h_f433348138"></a>

Click the "Install" button. You will be redirected to Shopify.

<figure><img src="/files/0f2aqZnEw8lJW2Wtnjkk" alt=""><figcaption></figcaption></figure>

### Step 3: Approve permissions <a href="#h_adf1a569ed" id="h_adf1a569ed"></a>

In Shopify, review the permissions and click the "Install" button. You'll then be asked to approve the subscription details.&#x20;

<figure><img src="/files/sSs3tWEUgBB5yUE0O7Es" alt=""><figcaption></figcaption></figure>

### Step 4: Set up your first extension <a href="#h_adf1a569ed" id="h_adf1a569ed"></a>

After successful installation, you will be redirected to the Platter+ dashboard. To begin, follow the instructions in our [quick start guide](/get-started/quick-start-guide), and begin optimizing your checkout.&#x20;

<figure><img src="/files/sGXbitL4GZiS4WFOBtMB" alt=""><figcaption></figcaption></figure>


# Quick start guide

Follow this guide to select, configure, and install your first checkout extension.

Whether you've just installed Platter+ or need a reminder on how to add an extension to your checkout, this guide will walk you through the process from start to finish.

{% hint style="warning" %}
**Plan requirement**

Your setup experience will vary based on your plan.&#x20;

* Basic: Post-purchase only
* Pro: Checkout extensions and post-purchase
  {% endhint %}

***

## Step 1: Select an extension

{% embed url="<https://youtu.be/SRkvD6IA5SQ>" %}

Platter+ has 10 checkout and post-purchase extensions to choose from. Choosing your first extension depends on your primary goal.&#x20;

We suggest starting with one of our most popular extensions:

* In-Checkout Cross-Sells
* Post-Purchase Offers
* Promotion Progress Bar
* Alert Banners
* Testimonials

{% hint style="warning" %}
If you need help selecting your first extension, use our [Checkout Optimization Checklist](/get-started/choosing-your-first-extension) as a guide.&#x20;
{% endhint %}

***

## Step 2: Configure the extension

{% embed url="<https://youtu.be/UU789qj5Uag>" %}

Once you've selected the extension you'd like to set up, use the configuration settings on the left-hand side.

Configuring the settings is pretty straightforward, but if you have questions or need help, refer to the documentation for each individual extension.

After you've finished adjusting the settings for an extension, follow these steps:

{% stepper %}
{% step %}
**Rename your extension**

<img src="/files/SGkShZ4IQe4lEyukTgjo" alt="" data-size="original">
{% endstep %}

{% step %}
**Click the `Save` button to save all of the settings**

<img src="/files/ylep4sc0YFjuTeXXp0IJ" alt="" data-size="original">
{% endstep %}

{% step %}
**Click the `+` icon to copy the Handle ID**

<img src="/files/OY4iPRVRNKVRBILNAsm6" alt="" data-size="original">
{% endstep %}
{% endstepper %}

***

## Step 3A: Installing an extension on your checkout page (Pro plan required) <a href="#installing-an-extension" id="installing-an-extension"></a>

Follow the steps below to add any of the checkout extensions to your checkout page.&#x20;

{% hint style="warning" %}
The steps to enable Post-Purchase Offers **differ** from those for adding checkout extensions (listed below). For detailed instructions on enabling Post-Purchase Offers, [**click here**](#installing-an-extension-1).
{% endhint %}

{% embed url="<https://youtu.be/fZNoYTXOAF4>" %}

Once you are finished setting up an extension, follow these steps:

{% stepper %}
{% step %}
**Click the `+` icon to copy the Handle ID**

<img src="/files/OY4iPRVRNKVRBILNAsm6" alt="" data-size="original">
{% endstep %}

{% step %}
**Click `Copy handle ID and go to editor`, it will open your checkout editor in a new tab**

<img src="/files/FPHKrN22hF5ovhETWhR1" alt="" data-size="original">
{% endstep %}

{% step %}
**Duplicate your live checkout (optional)**

<img src="/files/SwIl9l5Fr7PRjWeeMYeo" alt="" data-size="original">
{% endstep %}

{% step %}
**Click `Add app block`**

<img src="/files/vQFjFUnELYX8yxj6q6rJ" alt="" data-size="original">
{% endstep %}

{% step %}
**Search for Platter and select Checkout Extensions**

![](/files/hz5FnCRF3B65NL54g3fq)
{% endstep %}

{% step %}
**Adjust your checkout behavior settings**

<img src="/files/I6YG2UupC7UXKiD1OoMo" alt="" data-size="original">

{% hint style="info" %}
Depending on your requirements, we typically recommend deselecting `Allow app to block checkout` and selecting `Include app block in Shop Pay`.
{% endhint %}
{% endstep %}

{% step %}
**Paste your Handle ID**

<img src="/files/VvDwSoNonkhRyjo7hxrB" alt="" data-size="original">
{% endstep %}

{% step %}
**Drag the app block to your desired location**

<img src="/files/n505NYjhHXpQqwT4BHwa" alt="" data-size="original">
{% endstep %}

{% step %}

#### Publish the changes

<img src="/files/WMxBjmdZBfzyhq8VbcTr" alt="" data-size="original">
{% endstep %}
{% endstepper %}

## Step 3B: Enable your post-purchase page (Pro & Basic plans) <a href="#installing-an-extension" id="installing-an-extension"></a>

After creating the Post-Purchase Offers extension and adjusting the settings, navigate to your [Shopify Admin > Settings](https://admin.shopify.com/), and follow these steps:

{% embed url="<https://youtu.be/CdJSiUQzkyE>" %}

1. Open your [admin settings](https://admin.shopify.com/).&#x20;
2. Click on Checkout.\
   ![](/files/Hy0F5QfqkVJRrcfTN39y)
3. Scroll down to the post-purchase page section, and select Platter+.\
   ![](/files/0wtlsFCHPgfMuEyYQQme)
4. Save your changes.\
   ![](/files/w6FXuuN2zVtwN8mhwytk)

Once you have enabled this setting and activated your post-purchase page, your customers will see the offer(s) you set up in Post-Purchase Offers.

{% hint style="warning" %}
We suggest create a test purchase in order to make sure your Post-Purchase Offers are being displayed as expected.&#x20;
{% endhint %}


# Choosing your first extension

A simple guide to help you choose the best extensions for your goals and get started with Platter+.

## Checkout Optimization Checklist

Figuring out how to optimize your checkout can feel overwhelming for some, but that’s exactly why we made this guide—to help you find the extension(s) that work best for your checkout.

{% hint style="info" %}
**How to use this checklist:**

1. Identify your primary goal.
2. Select the recommended extensions based on that goal.
3. Use the follow-up questions to help configure your checkout extensions.
   {% endhint %}

{% stepper %}
{% step %}

## **Step 1: Determine your primary goal**

* [ ] **Increasing average order value (AOV)**

  *Encourage customers to spend more per order.*
* [ ] **Increasing checkout conversion rate (CVR)**

  *Reduce friction and guide customers smoothly through checkout.*
* [ ] **Improving clarity and trust with custom content**

  *Focus on providing reassurance, clear communication, and addressing customer concerns.*
  {% endstep %}

{% step %}

## Step 2: Recommended extensions for each goal

#### **Goal 1: Increasing average order value (AOV)**

* [ ] **In-Checkout Cross-Sells**

  *Recommend related or complementary products in the checkout process.*
* [ ] **Incentive Progress Bar**

  *Incentivize customer with tiered rewards like free shipping, free gifts, or product discounts to encourage higher spending.*
* [ ] **Post-Purchase Offers**

  *Present discounted complementary products after the initial purchase to maximize order value with minimal friction.*

#### **Goal 2: Increasing checkout conversion rate (CVR)**

* [ ] **Promotion Progress Bar**

  *Motivate customers to complete their purchase by showing progress towards discounts or free shipping.*
* [ ] **Testimonials**

  *Showcase customer reviews to increase confidence with customers.*
* [ ] **Alert Banners**

  *Highlight critical information (e.g., shipping deadlines, limited-time offers) to create urgency and increase transparency.*
* [ ] **Icon with Text**

  *Use trust badges or payment security icons to address frequently asked questions.*

#### **Goal 3: Building trust or improving customer support with custom content**

* [ ] **Text Block**

  *Provide detailed information (e.g., return policies, product FAQs) directly in the checkout.*
* [ ] **Image Block**

  *Use visual elements to reinforce trust (e.g., product guarantees, awards).*
* [ ] **Checkbox Input**

  *Collect information from customers to improve order quality (e.g., gift messages).*
* [ ] **Dropdown List**

  *Answer common questions about your products/services.*
  {% endstep %}

{% step %}

## **Step 3: Follow-up questions**

Once you’ve selected your goal, ask these follow-up questions to help set up the extensions:

**For improving AOV:**

* What products make sense for upsells, cross-sells, or post-purchase offers?
  * *Focus on products that are complementary, frequently bought together, or high-margin items.*
* Do you offer free shipping or product discounts?
  * *Use Promotion Progress Bar in checkout to incentivize customers to meet the threshold.*
* Are their products you do not want to upsell or cross-sell in checkout?
  * *Make sure to add them to* `Excluded Products`*.*

**For increasing CVR:**

* What specific information or signals would increase customer confidence?
  * *Highlight your return policy or shipping speed to reduce hesitation.*
  * *Use testimonials or trust badges to reinforce your credibility.*
* What pain points could cause customers to abandon checkout?
  * *Address them with targeted alert banners (e.g., “Free returns within 30 days!”).*

**For increasing customer confidence:**

* What details do your customers frequently ask about?
  * *Use text or dropdown blocks to proactively answer common questions.*
  * *Provide clear return or warranty policies for peace of mind.*
* Do your products require specific instructions or customization?
  * *Use checkboxes or dropdown lists to collect customization preferences or additional details like delivery instructions.*
    {% endstep %}
    {% endstepper %}

If you are unsure of what extensions are best for your brands or get stuck along the way, feel free to get in touch with us we will help you get set up.


# Overview

## What is a checkout page?

The checkout page is one of the most critical steps in your customer’s journey—it's where a customer makes the decision to add their payment information and buy your products.&#x20;

<figure><img src="/files/s0quLoJ7fPUeJjGA1VsW" alt=""><figcaption><p>Example of a checkout page.</p></figcaption></figure>

With Platter+ checkout extensions, you can easily modify your checkout page directly in Shopify. With an optimized checkout, you can:

* **Generate additional revenue** using cross-sells, upsells, and progress bars.
* **Increase customer confidence** using testimonials, badges, and frequently asked questions.
* **Improve conversion rates** with promotions, banners, and custom content.

## Where to edit your checkout page

Using Shopify's checkout editor, you can customize and manage the functionality and appearance of your checkout.

You can edit your checkout in your Shopify admin by clicking on Checkout, and then select Customize beside any of your checkout configurations.&#x20;

<figure><img src="/files/AXNyldLFQINduuX4iBaG" alt=""><figcaption><p>View of the checkout settings in Shopify.</p></figcaption></figure>

{% hint style="info" %}
To learn more about Checkout Extensibility, we suggest looking at Shopify's help center article on [Customizing and editing your checkout](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/index).&#x20;
{% endhint %}

## What are Platter+ checkout extensions?

Platter+ checkout extensions are powerful app blocks designed to help you enhance your checkout experience generate more revenue with every order. These extensions allow you to customize the functionality and appearance of your checkout page without needing technical expertise.

Platter+ offers a range of extensions:

* In-Checkout Cross-Sells
* Tiered Promotion Progress Bar
* Alert Banner
* Testimonials
* Checkbox With Input
* Dropdown Text
* Icons With Text
* Image Block&#x20;
* Text Block

Here is a preview of Platter+ checkout extensions in [Neuro](https://neurogum.com/)'s checkout.&#x20;

<figure><img src="/files/kfDNHZKwXjSxt1lMtSHG" alt=""><figcaption><p>An example of Platter+ checkout extensions in action.</p></figcaption></figure>


# Checkout extensions

In this section, you will learn about each type of checkout extension, see examples, and get detailed instructions on how to add them to your checkout.

Here are links to each type of extension:

* [In-Checkout Cross-Sells](/checkout/checkout-extensions/in-checkout-cross-sells)
* [Tiered Promotion Progress Bar](/checkout/checkout-extensions/promotion-progress-bar)
* [Alert Banner](/checkout/checkout-extensions/alert-banner)
* [Testimonials](/checkout/checkout-extensions/testimonials)
* [Checkbox With Input](/checkout/checkout-extensions/checkbox-with-input)
* [Dropdown Text](/checkout/checkout-extensions/dropdown)
* [Icons With Text](/checkout/checkout-extensions/icons-with-text)
* [Image Block ](/checkout/checkout-extensions/image-block)
* [Text Block](/checkout/checkout-extensions/text-block)


# Alert Banner

## What is an Alert Banner?

**Alert Banners** are used to display important updates, promotions, shipping information, or any other message you want to highlight during checkout.&#x20;

<figure><img src="/files/3g4pFEjrhG1gw2zw2znL" alt=""><figcaption><p>Example of a Warning alert.</p></figcaption></figure>

***

## Types of Alert Banners

There are four types of Alerts:

1. Info Alert
2. Success Alert
3. Warning Alert
4. Critical Alert

{% tabs %}
{% tab title="Info Alert" %}

#### Suggestion:

Use this alert type to share helpful, non-urgent information that guides customers during the checkout process, such as shipping promotions or policies.

<figure><img src="/files/CXjY9ZcfWJ3mDNpHqYuP" alt=""><figcaption><p>Example of an Info alert.</p></figcaption></figure>
{% endtab %}

{% tab title="Success Alert" %}

#### Suggestion:

Use this alert type to confirm details such as eligibility for discounts or free shipping. Success alerts help reassure customers and build confidence at checkout.

<figure><img src="/files/zzGw6o3j4PRZvOckx0C9" alt=""><figcaption><p>Example of a Success alert.</p></figcaption></figure>
{% endtab %}

{% tab title="Warning Alert" %}

#### Suggestion:

Use this alert type to warn customers about potential issues or encourage them to act quickly, such as low stock or expiring offers. Warnings are a great way of driving urgency or creating scarcity.

<figure><img src="/files/KkBdM3OzbMfcTaVSsq0r" alt=""><figcaption><p>Example of a Warning alert.</p></figcaption></figure>
{% endtab %}

{% tab title="Critical Alert" %}

#### Suggestion:

Use this alert type to highlight urgent issues that require immediate customer action, such as completing their order. Critical alerts are a valuable way to prevent abandoned checkouts and decrease customer errors.

<figure><img src="/files/XIHKyLDc1bNMDpvM6uMP" alt=""><figcaption><p>Example of a Critical alert.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

***

## Configuring Alert Banners

Follow the instructions below to setup an **Alert Banner:**

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the extension you'd like to set up and click **Add to Checkout.**
3. Open the **Settings** window, and adjust the content and styling of the Alert Banner.\
   ![](/files/3HKVs9tmydOJopG1Ar2o)
4. Enter a custom name (optional).\
   ![](/files/7D54shxWrqqMuE4GihhD)
5. Click the **`+`** icon to copy the Handle to your clipboard.\
   ![](/files/Bu8UB42qnBL8TSP9Svp1)
6. Hit **`Save`** to to ensure your settings and saved.
7. Open your Checkout Editor and [install your extension](/get-started/quick-start-guide#installing-an-extension).


# Checkbox With Input

## What is a Checkbox With Input?

**Checkbox With Input** enables you to collect additional information from customers during checkout by adding a checkbox and text field. Common use cases include asking customers if their order is a gift, allowing them to provide gift details, or letting them add special delivery instructions. This feature helps merchants gather important customer information during checkout.

<figure><img src="/files/VF5jeo5UShYQKeuIrHki" alt=""><figcaption><p>Example of a Checkbox With Input extension.</p></figcaption></figure>

***

## How to configure a Checkbox With Input?

Follow the instructions below to setup a **Checkbox  With Input**.

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the extension you'd like to set up and click **Add to Checkout.**
3. Open the **Settings** window, and adjust the content of the Checkbox Input. ![](/files/bl0hBjdzkp7ZpmVoyRuy)
4. Select whether you want customers to be able to input text using the **`Trigger a text input for a note`** checkbox.\
   ![](/files/dlWnf7JBwbfi4d7bON7S)
5. Change the call to action in the text box and select the default state (checked or unchecked).\
   ![](/files/FwasogKWmfSciguSOn9z)
6. In the **Install extensions in checkout** editor window, enter a custom name (optional).\
   &#x20;![](/files/7D54shxWrqqMuE4GihhD)
7. Click the **`+`** icon to copy the Handle to your clipboard.\
   &#x20;![](/files/Bu8UB42qnBL8TSP9Svp1)
8. Hit **`Save`** to to ensure your settings and saved.
9. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Draft order

## What is a Draft Order?


# Dropdown

## What is a Dropdown?

A **Dropdown** allows you to add a customizable drop-down text to the checkout, where you can address commonly asked questions, such as delivery times, product questions, or warranty information.

<figure><img src="/files/x4cmpKgG2Cku4GEv4AeU" alt=""><figcaption><p>Example of a Dropdown extension.</p></figcaption></figure>

***

## How to configure a Dropdown?

Follow the instructions below to setup a **Dropdown:**

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the extension you'd like to set up and click **Add to Checkout.**
3. Open the **Settings** window, and adjust the heading of the Dropdown.\
   ![](/files/XfYeWPHoROXexBASlJaD)
4. Edit the title and body text for each dropdown (to a max of 3).\
   ![](/files/bVOZP4dSjg6qezWXaSx5)
5. If you would like to delete a dropdown, click the trash icon.\
   ![](/files/D0ONIvFZq8u50NCElPVd)
6. If you would like to add an icon, click Add Dropdown.\
   ![](/files/hxeFtkTO3uSxQiC4Y9mJ)
7. Enter a custom name (optional).\
   &#x20;![](/files/7D54shxWrqqMuE4GihhD)
8. Click the **`+`** icon to copy the Handle to your clipboard.\
   &#x20;![](/files/Bu8UB42qnBL8TSP9Svp1)
9. Hit **`Save`** to to ensure your settings and saved.
10. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Dynamically Priced Upsell

## What is a Dynamically Priced Upsell?

A **Dynamically Priced Upsell** is an upsell offer presented during the checkout process, where the price of the suggested product adjusts based on the items already in the customer’s cart.

***

## How to configure a Dynamically Priced Upsell?

Follow the instructions below to setup a **Dynamically Priced Upsell**.

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the extension you'd like to set up and click **Add to Checkout.**
3. Open the **Settings** window, and adjust the content and styling of the Dynamically Priced Upsell.\
   ![](/files/NSOJ3p2ed98UWEvrHEkb)
4. Set the price.\
   ![](/files/lIJAn0dpmWHjUjwSmWBX)
5. Customize the content settings.\
   ![](/files/yFk8CiVdihFpyZApmqRB)
6. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
   &#x20;![](/files/7D54shxWrqqMuE4GihhD)
7. Click the **`+`** icon to copy the Handle to your clipboard.\
   &#x20;![](/files/Bu8UB42qnBL8TSP9Svp1)
8. Hit **`Save`** to to ensure your settings and saved.
9. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Icons With Text

## What is an Icon With Text?

The **Icons With Text** feature enables you to add visual icons alongside text within the checkout to highlight key information, such as secure payment options or shipping guarantees, enhancing the customer experience.

<figure><img src="/files/dGyGO6SjbHAsBD2P5dBd" alt=""><figcaption><p>Example of a Icons With Text extension.</p></figcaption></figure>

***

## How to configure an Icon With Text?

Follow the instructions below to setup an **Icon With Text**.

{% embed url="<https://app.arcade.software/share/ledrzwOc7Efu5LlESdsC>" %}

1. From the dashboard, go to **Extensions** tab or click **`Browse extensions`**.\
   ![](/files/ZlgQ2MklWfk2osa0xlYE)
2. In the Extensions page, scroll down and find the **Icons With Text** extension you'd like to set up and click **`Add to Checkout`.**\
   ![](/files/Zeg4fr8jD27RadkoTUJ6)
3. Select the markets you'd like to display the extension. \
   ![](/files/UDGkmREi1bT82D9j5J4q)
4. Open the **Settings** window, and adjust the content and styling.\
   ![](/files/kLEcDbw3Ap3nwnJoFvSF)
5. Open the **Icon with Text** window to customize the icon and text.\
   ![](/files/wkZwXQT2xz43mm8o4Tl0)
6. To add more icons, click the **`Add icon with text`** button and repeat the process.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">You can use up to maximum of 3 icons with text.</mark>\
   ![](/files/39viRbb1G7EWQjtCYPRG)
7. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
   ![](/files/MCNvWBZvZcafI3gLXo9M)
8. Click the **`+`** icon to copy the Handle to your clipboard. \
   ![](/files/ABfjKxPVWMifsXYyixK3)
9. Hit **`Save`** to to ensure your settings and saved.\
   ![](/files/vmlsI7vnygY0YBPa6k3i)
10. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Image Block

## What is an Image Block?

**Image Blocks** are exactly what you'd expect them to be, high quality images that can be added to your checkout page. They can be used for a variety of purposes such as adding branded imagery to your checkout, warrant and shopping badges, payment information, and anything else that is supported by custom image blocks.&#x20;

***

## How to configure an Image Block?

Follow the instructions below to setup an **Image** **Block**.

{% embed url="<https://app.arcade.software/share/UnWVJm0NNIbog2HM2rMy>" %}

1. From the dashboard, go to **Extensions** tab or click **`Browse extensions`**.\
   ![](/files/ZlgQ2MklWfk2osa0xlYE)
2. In the Extensions page, scroll down and find the **Image Block** extension and click **`Add to Checkout`.**
3. Select the markets you'd like to display the extension.\
   ![](/files/UDGkmREi1bT82D9j5J4q)
4. Open the **Settings** window, add a custom image and adjust the sizing.\
   ![](/files/pMbObkHVj634V5uQm8z8)
5. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
   ![](/files/9E2BiAGApLs8B9Z1uRJK)
6. Click the **`+`** icon to copy the Handle to your clipboard.\
   ![](/files/IFcIktz6NQCw89HXelnQ)
7. Hit **`Save`** to to ensure your settings and saved.\
   ![](/files/51msskM6slzQunzoXrTz)
8. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Promotion Progress Bar

## What is an Promotion Progress Bar?

Using the **Promotion Progress Bar** in your checkout is a great way to incentivize customers to increase their cart value by offering rewards, such as free shipping or a discount.&#x20;

<figure><img src="/files/PLqAvfSpUextI4RxhAKz" alt=""><figcaption><p>Example of the Promotion Progress Bar extension.</p></figcaption></figure>

What makes Platter+ so powerful, is that **you can stack up to three promotions into the same progress bar**. For example, you can incentives customers with:

* Free shipping
* A percentage discount off their order
* A free gift if they spend over a certain amount

### How does the Promotion Progress Bar function?

The promotions in the Promotion Progress Bar is are based on the following:

1. **Subtotal:** The subtotal of the items in the customer's cart (before taxes, discounts applied at checkout and shipping).
2. **Quantity:** The number of items in the customer's cart.

### What types of discounts can be used?

With Platter+, you can use the Promotion Progress Bar to promote three different discount types:

{% tabs %}
{% tab title="Shipping discount " %}
Increase order value by offering free shipping when customers hit a specific target.

<figure><img src="/files/3W7LA0tMjbq6osqH0nZ9" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Product discount" %}
Offer a free/discounted product when customers reach a specific spending threshold or buy specific products.

<figure><img src="/files/xQSP2lv6IctVT92hV8LJ" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Order discount" %}
Offer a percentage or fixed discount on order when customers spend a minimum amount.&#x20;

<figure><img src="/files/0D3m3u5v5LAVEMvvhUc8" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## How are discounts in the Promotion Progress Bar applied to the order?

<figure><img src="/files/9JVQ5zj3wGKK4lGYWU09" alt=""><figcaption></figcaption></figure>

Any discounts you're offering will need to be created using [Discounts](https://admin.shopify.com/discounts) in your Shopify admin. This can be done by creating Automatic Discounts.

{% hint style="info" %}
For more information on how to create discounts in Shopify, refer to [Shopify's article on discount types](https://help.shopify.com/en/manual/discounts/discount-types).&#x20;
{% endhint %}

***

## How to configure a Promotion Progress Bar?

Follow the instructions below to setup an **Promotion Progress Bar:**

1. From the dashboard, go to **Extensions** tab or click **`Browse extensions`**.\
   ![](/files/Uf7yAQUwJPRpaFHxqxgH)
2. In the Extensions page, scroll down and find the **Promotion Progress Bar** extension and click **`Add to Checkout`.**
3. Select the markets you'd like to display the extension.\
   ![](/files/UDGkmREi1bT82D9j5J4q)
4. In the Promotional Details, select how you'd like the Promotion Progress Bar to activate.\
   ![](/files/cpk8uveiG7HtQExWsjo6)
5. If you'd like, add header text.\
   ![](/files/v9gsugLhDaRk8b6WqhtV)
6. If your promotion only applies to when customers have certain items in their order (ie. "Buy jeans, get a free t-shirt"), specify what products should trigger the promotion.\
   ![](/files/NVxIqoTr4CGgUvSbLEr3)
7. Select the discount type you'd like to use for the first promotion (shipping, order, or product).\
   ![](/files/1AH6NU1NdtEfDoxoVlTN)
8. Then, select the minimum subtotal/quantity the customer must add to their order in order to be eligible for the promotion.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Promotions are calculated based on the cart's subtotal before discount codes are applied at checkout. If the subtotal below the minimum after the discount code is applied, the customer will still qualify for the promotion. This is a Shopify limitation.</mark>\
   ![](/files/W2CMQVBoQ2RlQypPPGAb)
9. Next, select what discount method you'd like to use, either percentage off (%) or fixed amount ($). And set the discount percentage or dollar amount.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">When using the product discount type, the discount method applies individually to each eligible promotional product. For example, if your promotion is "Buy a pair of pants, get $5 off two shirts," each shirt will receive a $5 discount, resulting in a total discount of $10.</mark>\
   ![](/files/nReeCLOuJMY3LP2nfWfm)
10. Edit the message shown before and after the customer becomes eligible for the promotion.\
    ![](/files/CslSO664yC2SmroQOnw5)
11. To create additional offers/promotions, click the **`Add offer`** button.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">You can use up to three offers/promotions at one time.</mark>
12. If you are using a second or third offer, repeat steps 7-10 for each additional offer.&#x20;
13. If you desire, adjust the header and border styling.\
    ![](/files/6KNtf1l6ZOgLVVcJ5wKM)
14. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
    ![](/files/zYyf8sGe2W7C2XrBrYxj)
15. Click the **`+`** icon to copy the Handle to your clipboard.\
    ![](/files/ZXdhyP29Zb1R3FS24gwC)
16. Hit **`Save`** to to ensure your settings and saved.\
    ![](/files/51msskM6slzQunzoXrTz)
17. Before moving to the next step, make sure that you have [created automatic discounts in Shopify](#how-are-discounts-in-the-promotion-progress-bar-applied-to-the-order) that match the offers you have set up in the previous steps.\
    Note: If you do not create corresponding automatic in Shopify, your
18. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Product Discount

## What is a Product Discount?

A **Product Discount** offers a discounted (or free) product when a customer reaches a certain spending amount. This can be a specific product or a selection of items the customer can choose from.

**Example**: “Spend $75 and get a free gift!”

## How to configure a Product Discount?


# Order Discount

## What is a Order Discount?

An **order discount** incentivizes customers to increase their cart value by offering a percentage or fixed amount off once they spend a certain amount. This is an effective way to encourage customers to spend more to unlock savings.

**Example**: “Spend $100 and get 10% off your order!”

## How to configure an Order Discount?


# Shipping Discount

## **What is a Shipping Discount?**

Shipping discounts, most commonly **free shipping**, are a powerful incentive used to motivate customers to increase their cart value. By offering free shipping once the customer reaches a specific spending threshold, merchants can reduce cart abandonment and boost the average order value (AOV).

**Example**: “Spend $50 to get free shipping!”

***

## How to configure a Shipping Discount

<mark style="color:red;">Add a video/arcade here</mark>


# In-Checkout Cross-Sells

## What are In-Checkout Cross-Sells?

**In-Checkout Cross-Sells** allow your customers to add complementary products to their order with a single click during checkout. This feature increases your average order value (AOV) by offering relevant product recommendations at the final stage of the purchase process.

<figure><img src="/files/i3qKLjQ23UIPZbzjmjsb" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
In order to maximize revenue with In-Checkout Cross-Sells, we recommend pairing it with[Promotion Progress Bar](/checkout/checkout-extensions/promotion-progress-bar)in your checkout for even greater impact.
{% endhint %}

***

## How to configure In-Checkout Cross-Sells?

Follow the instructions below to setup an **In-Checkout Cross-Sells:**

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the **In-Checkout Cross-Sells** extension and click **`Add to Checkout`.**
3. Open the **Select your markets** window, and confirm the correct market is selected. \
   ![](/files/mWKkmgVpCC3B6BfEKQDB)
4. Edit the header text.\
   ![](/files/DUN5uVQGAjtOUjYl1Mb5)
5. Select the number of products to cross-sell in your checkout. As a best practice, we suggest starting with three offers.\
   ![](/files/PBDhaMbaj4pr1bBVj6TS)<br>
6. Set the hierarchy of your cross-sell offer groups. To hide an offer group, click the **`x`** icon.\
   ![](/files/OVP6EC2fOtdVV6Vqqlk7)
7. To manage your offer groups or to , click **`View all groups`**.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Offer groups are a group or collection of products that will be cross-sold in your checkout based on the hierarchy you set. If you would like to upsell a specific product, you can add one product to a custom offer group.</mark> \
   ![](/files/XxzW8UUlZhBSubJlCgdM)
8. To create a new offer group, click the **`Add new group`** button.\
   ![](/files/Kv7QVMg9HzuEUjiRpJ0q)
9. Add an offer group name, select the cross-sell type (products or collection), and select the products that you would like to include in that offer group. Make sure **`Save changes`** when your done. \
   ![](/files/NDLSo43SRcAkp2uUFzuW)
10. Once you are done creating a new group, select the offer groups you would like to display in your checkout.\
    ![](/files/RTfgat4buv1vfdYbqoBY)
11. If you would like to exclude certain products from being displayed, click **`Browse`** and select the products you would like to hide. \
    ![](/files/oaNpOQKhSOn0fuvDsKPA)&#x20;
12. Next, manage the discount you would like to apply the Post-Purchase Offers.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Fixed amount discounts are not available when more than one market is selected.</mark>\
    ![](/files/JYvJQloXWZ6kblfb01UX)
13. Edit the discount name.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Customers will see this discount name. It will be shown under the line item in the final checkout screen.</mark>\
    ![](/files/W6taffu8Qe0t2LjudtjH)
14. Once you are finished, make sure to **`Save`** your settings. \
    ![](/files/AWlwA2gEkp348090ryg7)
15. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# What is a Cross-Sell group?

## What is a Cross-Sell?

**Cross-selling** is a sales technique where customers are encouraged to purchase complementary or related products in addition to the items they’re already buying. The goal of cross-selling is to increase the total value of a customer’s order by offering products that enhance or complement the primary purchase.

For example, if a customer is purchasing a laptop, cross-selling would suggest additional items like a laptop case, external mouse, or an extended warranty. Cross-selling can occur at various stages of the customer journey, including **during checkout** or as a **post-purchase offer**.

## What is a cross-sell group?

A **cross-sell group** is a set of products or collections that are recommended to customers during the checkout process. These products are complementary to the items already in the customer’s cart and are intended to increase the average order value (AOV) by encouraging the customer to add additional items.

Cross-sell groups can be used in different stages of the customer journey, including **in-checkout** or **post-purchase**, to offer relevant product suggestions without disrupting the checkout flow.

## Why use cross-sell groups?

Cross-sell groups help merchants to:

* **Increase average order value (AOV)** by suggesting complementary products that customers may have overlooked.
* **Provide a better shopping experience** by recommending items that are relevant to the customer’s purchase, making it more likely they’ll find value in the additional products.
* **Automate upselling** by setting up pre-configured cross-sell groups that show the right products at the right time.

For example, if a customer adds a camera to their cart, they might be shown cross-sell products like memory cards, camera bags, or extra batteries from a pre-configured cross-sell group.

***

## How to create custom cross-sell groups?

{% embed url="<https://app.arcade.software/share/XHivVkryX5TMI08POLmY>" %}


# Discounts


# Testimonials

## What is a Testimonial?

A **Testimonial** is a great way to showcase customer reviews and feedback during checkout, building trust and encouraging new customers to complete their purchase confidently.

<figure><img src="/files/n7dKdeat3cYsp61Asxf4" alt=""><figcaption><p>Example of a Testimonial.</p></figcaption></figure>

***

## How to configure a Testimonial?

Follow the instructions below to setup a **Testimonial**.

{% embed url="<https://app.arcade.software/share/0wP8JW5zrvVLRVfmz5t9>" %}

1. From the dashboard, go to **Extensions** tab or click **`Browse extensions`**. ![](https://docs.platter.co/~gitbook/image?url=https%3A%2F%2F3290803092-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FrQAMmskYzr7YduJvnmdP%252Fuploads%252F0qDogng1LODcvJyWc0bI%252FScreenshot%25202025-01-13%2520at%25209.23.03%2520AM.png%3Falt%3Dmedia%26token%3D2cf56613-0432-4d52-9c89-25c47cf9d4d1\&width=300\&dpr=4\&quality=100\&sign=ee26a011\&sv=2)
2. In the Extensions page, scroll down and find the **Testimonials** extension and click **`Add to Checkout`.**
3. Select the markets you'd like to display the extension. ![](https://docs.platter.co/~gitbook/image?url=https%3A%2F%2F3290803092-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FrQAMmskYzr7YduJvnmdP%252Fuploads%252F63X452MplcW6iarczRZb%252FScreenshot%25202025-01-13%2520at%25209.26.30%2520AM.png%3Falt%3Dmedia%26token%3Dee0f9df4-4fa1-492e-bc2f-3484a209d944\&width=300\&dpr=4\&quality=100\&sign=fb40706\&sv=2)
4. Open the Settings window and edit the heading as well as the border. ![](https://docs.platter.co/~gitbook/image?url=https%3A%2F%2F3290803092-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FrQAMmskYzr7YduJvnmdP%252Fuploads%252F4QVVSgUj2tALpMLS6Pb1%252FScreenshot%25202025-01-15%2520at%25202.16.56%2520PM.png%3Falt%3Dmedia%26token%3D4f5c37de-9519-48a7-8ae4-e3a97fcfa792\&width=300\&dpr=4\&quality=100\&sign=d175ea25\&sv=2)
5. Open the **Install extension in checkout editor** window, and enter a custom name(optional).
6. To add a testimonial, click Add testimonial.\
   ![](/files/DPKoJI3KnCR9xe3c1qIn)
7. Add your testimonial.\
   ![](/files/g058BXbic8nWRVJkjJzI)
8. Add the reviewer name.\
   ![](/files/KwFIWz1UE1HpgopGAdTr)
9. Add a star rating for the testimonial.\
   ![](/files/6eKpOMpWd6exb2CrRJxv)
10. To add an additional testimonial, click the **`Add testimonial`** button and repeat steps 7-9.\
    ![](/files/f2Tlmf7BXCi63B8zepS2)
11. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
    ![](/files/NGFzPdGyYWzUpro7ST8B)
12. Click the **`+`** icon to copy the Handle to your clipboard. \
    ![](/files/jbRJ3tOt5QNuzF9y3aZr)
13. Hit **`Save`** to to ensure your settings and saved. \
    ![](/files/MPVKdEOxN4brVF5szlAI)
14. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).


# Text Block

## What is a Text Block?

**Text Blocks** allow you to add customizable text in the checkout, providing important information or instructions to customers.

***

## How to configure a Text Block?

Follow the instructions below to setup a **Text Block**.

{% embed url="<https://app.arcade.software/share/PzZYLlsOMGZToiwCsTtg>" %}

1. From the dashboard, go to **Extensions** tab or click **`Browse extensions`**.\
   ![](/files/ZlgQ2MklWfk2osa0xlYE)
2. In the Extensions page, scroll down and find the **Text Block** extension and click **`Add to Checkout`.**
3. Select the markets you'd like to display the extension.\
   ![](/files/UDGkmREi1bT82D9j5J4q)
4. Open the Settings window and edit the heading as well as the border. \
   ![](/files/CZX3Cukt01rLFidEhdOT)
5. To add a paragraph of text, click **`Add paragraph`**.\
   ![](/files/xXcgSghyIHz74UXC16lZ)
6. Add your desired text.\
   ![](/files/dLRANxGOTHB4ekrr37dZ)
7. Adjust the style settings.\
   ![](/files/BlBgc0lCxcult2yqov6y)
8. If you'd like to add another paragraph, click the **`Add paragraph`** button and repeat steps 5-7.
9. Open the **Install extension in checkout editor** window, and enter a custom name (optional).\
   ![](/files/4gL9g9CPUcpQVV3nYj54)
10. Click the **`+`** icon to copy the Handle to your clipboard.\
    ![](/files/LngRUewUxUFSRQNUVaJn)
11. Hit **`Save`** to to ensure your settings and saved.\
    ![](/files/bmnh2jbGkNQ8rpHtvgfK)
12. Open your Checkout Editor and [install your extension](https://docs.platter.co/~/changes/QMi520wn6lsXSXuRamqi/get-started/get-started-in-3-steps#installing-an-extension).<br>


# FAQs


# Overview

## What is post-purchase?

To keep it simple, your checkout typically has two parts:

1. The checkout page
2. The thank you page

Using [post-purchase checkout extensions](https://shopify.dev/docs/apps/build/checkout/product-offers#checkout-extensions), you can add an additional page that appears after the order is confirmed, but before the thank you page. Which means your checkout will then have three parts:

1. The checkout page
2. The post-purchase page
3. The thank you page

On the post-purchase page, [post-purchase product offers](https://shopify.dev/docs/apps/build/checkout/product-offers#post-purchase-product-offers) allow you to prompt a customer to add more products to their initial order after they've completed payment.

<figure><img src="/files/bFLSEqcWGM5tBx5wBlsJ" alt=""><figcaption><p>Example of a post-purchase product offer.</p></figcaption></figure>

Accepted offers are added to the initial purchase, allowing customers to add more items to their order with a click of a button. Despite appearing as multiple authorizations, customers will only see a single charge on their statement.

## What are Platter Post-Purchase Offers?

Platter's Post-Purchase Offers extension allows you to set up personalized offers to display to customers after they complete checkout.&#x20;

<figure><img src="/files/oCYlfJn1PcB3patTvJHL" alt=""><figcaption><p>The configuration settings for Post-Purchase Offers in the Platter+ app.</p></figcaption></figure>

Behind the scenes, you control which products are displayed to customers. And in the front end, the customer sees an additional page after checkout, allowing them to seamlessly add products to their order.

The following is a basic example of how the post-purchase offer is displayed to a customer during checkout:

<figure><img src="/files/ODulouu6BRn8Rip95TAV" alt=""><figcaption></figcaption></figure>

## Limitations to keep in mind for post-purchase extensions

Post-purchase offers are a powerful way to boost your average order value, but there are some limitations you should be aware of to ensure they meet your store's criteria.&#x20;

Below is a list of limitations and considerations for post-purchase checkout extensions from Shopify:

| Area                                       | Context                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment provider                           | Third-party payment providers that require the customer’s CVN/CVV to be retained aren't supported. This might include, but isn't limited to, payment providers such as Braintree, Payflow Pro, PayPal Payments Pro, and Eway.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Additional payment methods                 | <p>The post-purchase page won't be surfaced in the following scenarios:</p><ul><li>The customer chooses to check out with an installment service or a wallet service (such as Klarna, Affirm, AfterPay, Apple Pay, Amazon Pay, or Google Pay).</li><li>The initial purchase was made with a gift card or any payment method other than a credit card.</li></ul>                                                                                                                                                                                                                                                                                                                                                   |
| Purchase events                            | Third-party analytic services that use the Shopify Pixel API (such as Google Analytics, Facebook, Pinterest and Snap) report only the purchase event and value for the initial purchase.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Analytics                                  | Third-party analytics services that use the [`ScriptTag`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ScriptTag) object or [additional scripts](https://help.shopify.com/manual/orders/status-tracking/customize-order-status#add-additional-scripts) have incomplete conversion data, because they're only triggered on the **Order status** page.                                                                                                                                                                                                                                                                                                                                                 |
| Duties and support for multiple currencies | Post-purchase upsell offers won’t be surfaced on orders with duties and multiple currencies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Order creation delays                      | In scenarios such as flash sales where the Shopify Platform is under extreme load, our system might optimize to capture orders but briefly delay the order creation step for a fast and seamless buyer experience. In these scenarios, post-purchase pages won't be surfaced, even if the request for the post-purchase page was properly made.                                                                                                                                                                                                                                                                                                                                                                   |
| Multiple apps                              | Merchants with multiple apps that have the post-purchase checkout extension need to select which app appears on the post-purchase page. You can use a banner during app onboarding to let merchants know that they can [select your app](https://shopify.dev/docs/apps/build/checkout/product-offers/ux-for-post-purchase-product-offers#post-purchase-app-selector) as the default post-purchase app in the Shopify admin checkout settings.                                                                                                                                                                                                                                                                     |
| Fulfillment holds                          | <p>Shopify places a hold on fulfillment for all orders undergoing a post purchase cross-sell flow. Holds are released either when the customer visits the <strong>Order status</strong> page, or after a set amount of time, if the customer doesn't complete the post-purchase flow.<br><br>If the customer doesn't complete the flow (for example, the customer closes the browser before actioning the post-purchase upsell offer), then the fulfillment hold is lifted one hour after submission of the initial checkout. Fulfillment holds are only supported using the <a href="https://shopify.dev/docs/api/admin-graphql/latest/objects/fulfillmentorder"><code>FulfillmentOrder</code></a> resource.</p> |
| Interaction with the **Order status** page | The post-purchase page shouldn't be used as a replacement for the **Order status** page. For more information, refer to the [customer flow](https://shopify.dev/docs/apps/build/checkout/product-offers#post-purchase-product-offers#how-it-works).                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| API versioning                             | The post-purchase checkout extension APIs aren't versioned and don't follow the [Shopify API versioning](https://shopify.dev/docs/api/usage/versioning) quarterly release schedule.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Orders without a shipping address          | <p>If the customer's checkout results in the creation of an order without a shipping address, then you can't add a subscription to the order using post-purchase. For example, a customer might have bought only digital products, which doesn't require a shipping address.<br><br>Similarly, a customer might choose local pickup as their delivery method, which also doesn't require a shipping address. You can determine in advance whether a shipping address exists by viewing the payment step within the <code>ShouldRender</code> extension point. If the <code>destinationCountryCode</code> input field is <code>null</code>, then no shipping address is set.</p>                                   |
| Orders for local delivery                  | Post-purchase upsell offers won’t be surfaced on orders for local delivery.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Minimum order price                        | Orders need to be $0.50 or more to qualify for post-purchase offers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Accepted offers                            | A customer can accept a maximum of three post-purchase offers for each checkout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Number of post-purchase pages              | You can create only one post-purchase page. However, because a post-purchase extension is a single-page app, you can paginate the single page to create multiple pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Sales channel                              | Orders need to be placed through the Online Store sales channel to qualify for post-purchase upsells. Other sales channels won't render post-purchase upsell pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Storage API with Shop Pay                  | When buyers check out using Shop Pay, the `Render` extension target can't read data that's stored in the [Storage API](https://shopify.dev/docs/api/checkout-extensions/post-purchase/api#storage) during the `ShouldRender` extension target. This is because the targets are running in different domains (`shop.app` and the merchant's domain).                                                                                                                                                                                                                                                                                                                                                               |

{% hint style="info" %}
For more information on the limitations of post-purchase extensions, refer to [Shopify's documentation](https://shopify.dev/docs/apps/build/checkout/product-offers#limitations-and-considerations).&#x20;
{% endhint %}


# Post-Purchase Offers

Adding a Post-Purchase offer to your checkout is done in two simple steps:

1. [Configuring your Post-Purchase Offer](#configuring-post-purchase-offers)
2. [Enabling your post-purchase page in Shopify](#enabling-your-post-purchase-page-in-shopify)

## Configuring Post-Purchase Offers

Follow the instructions below to setup a **Post-Purchase Offer:**

1. From the dashboard, go to **Extensions** tab.
2. In the Extensions page, scroll down and find the **Post-Purchase Offers** extension and click **Add to Checkout.**
3. Open the **Select your markets** window, and confirm the correct market is selected. \ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Post-Purchase Offers are only available for your store's primary market and currency.</mark> \
   ![](/files/WYIvIXLSnxLfbqGriqpR)
4. Edit the text that will be displayed in your offer.\
   ![](/files/LMIrrzhei2kMYS1anHT9)
5. Select the number of offer to show to customers.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">One offer is shown at a time. The maximum number of offers you can display is two. This is a Shopify limitation.</mark> \
   ![](/files/MWJ8bsXPnZqBlkHzFkj9)
6. Set the hierarchy of your post-purchase offer groups. To hide an offer group, click the **`x`** icon.\
   ![](/files/slnCHiqwWgW1ffzXV7eJ)
7. To manage your offer groups or to , click **`View all groups`**.\ <mark style="color:red;">**Note:**</mark> <mark style="color:red;"></mark><mark style="color:red;">Offer groups are a group or collection of products that will be displayed in your Post-Purchase Offers based on the hierarchy you set. If you would like to upsell a specific product, you can add one product to a custom offer group.</mark> \
   ![](/files/2AFK5ZtcGSjQDn1gdP90)
8. To create a new offer group, click the **`Add new group`** button.\
   ![](/files/Kv7QVMg9HzuEUjiRpJ0q)
9. Add an offer group name, select the cross-sell type (products or collection), and select the products that you would like to include in that offer group. Make sure **`Save changes`** when your done. \
   ![](/files/NDLSo43SRcAkp2uUFzuW)
10. Once you are done creating a new group, select the offer groups you would like to display in Post-Purchase Offers.\
    ![](/files/RTfgat4buv1vfdYbqoBY)
11. If you would like to exclude certain products from being displayed, click **`Browse`** and select the products you would like to hide. \
    ![](/files/oaNpOQKhSOn0fuvDsKPA)&#x20;
12. Next, manage the discount you would like to apply the Post-Purchase Offers.\
    ![](/files/HeQHRdcmZSLo0ZeVHLFc)
13. Once you are finished, make sure to **`Save`** your settings. \
    ![](/files/AWlwA2gEkp348090ryg7)

## Enabling your post-purchase page in Shopify

{% embed url="<https://youtu.be/CdJSiUQzkyE>" %}

After creating the Post-Purchase Offers extension and adjusting the settings, navigate to your [Shopify Admin > Settings](https://admin.shopify.com/), and follow these steps:

1. Open your [admin settings](https://admin.shopify.com/).&#x20;
2. Click on Checkout.\
   ![](/files/Hy0F5QfqkVJRrcfTN39y)
3. Scroll down to the post-purchase page section, and select Platter+.\
   ![](/files/0wtlsFCHPgfMuEyYQQme)
4. Save your changes.\
   ![](/files/w6FXuuN2zVtwN8mhwytk)

Once you have enabled this setting and activated your post-purchase page, your customers will see the offer(s) you set up in Post-Purchase Offers.

{% hint style="warning" %}
We suggest create a test purchase in order to make sure your Post-Purchase Offers are being displayed as expected.&#x20;
{% endhint %}


# FAQs

Here are answers to the most commonly asked questions about Platter+. Explore the topics below to find detailed answers:

{% content-ref url="/pages/vzNTGTIEwGO8ie08zi1k" %}
[Is Platter+ compatible with my Shopify store?](/resources/faqs/is-platter+-compatible-with-my-shopify-store)
{% endcontent-ref %}

{% content-ref url="/pages/TD0ryabAb1mVGagCXG0p" %}
[How much does Platter+ cost?](/resources/faqs/how-much-does-platter+-cost)
{% endcontent-ref %}

{% content-ref url="/pages/MA8fAOmWfjLyaFl0i0Mg" %}
[What is a Handle ID?](/resources/faqs/what-is-a-handle-id)
{% endcontent-ref %}

{% content-ref url="/pages/9DpTcsWkWEu32aNwSGcy" %}
[How can I track revenue generated with Platter+?](/resources/faqs/how-can-i-track-revenue-generated-with-platter+)
{% endcontent-ref %}

{% content-ref url="/pages/9HlM1VfJm9NFQRrWRbwE" %}
[Can I get help setting up extensions?](/resources/faqs/can-i-get-help-setting-up-extensions)
{% endcontent-ref %}

{% content-ref url="/pages/F2e1sZI9qg2cRuGWGWbb" %}
[How do I remove an extension?](/resources/faqs/how-do-i-remove-an-extension)
{% endcontent-ref %}


# Is Platter+ compatible with my Shopify store?

Platter+ offers features that are compatible with both Shopify and Shopify Plus stores.

* **Shopify Plus stores** can unlock advanced checkout customizations through Shopify's checkout extensibility, which Platter+ is built to support.
* **Shopify stores** (on plans other than Plus) can still benefit from Platter+'s post-purchase customizations, enabling you to optimize the customer journey after checkout.

To learn more about checkout extensibility and its requirements for Shopify Plus stores, visit [Shopify's documentation](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility).

{% embed url="<https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility>" %}


# How much does Platter+ cost?

Platter+ pricing is designed to scale with your success and guarantees a minimum **5x return on investment (ROI)**. It’s based on the **Processed Gross Revenue** you generate using Platter+ features and is calculated monthly.

| Plan Name  | Cost                                                              | Processed Gross Revenue |
| ---------- | ----------------------------------------------------------------- | ----------------------- |
| Start      | Free                                                              | Up to $1,250            |
| Launch     | $249                                                              | Up to $2,500            |
| Grow       | $499                                                              | Up to $5,000            |
| Scale      | $749                                                              | Up to $7,500            |
| Enterprise | $749 *+ 5% commission on all Processed Gross Revenue over $7,500* | Greater than $7,500     |

{% hint style="warning" %}
**Have questions or want to see Platter+ in action?** Get in touch with our team at <hello@platter.co> or [schedule a demo](https://www.platter.co/book-demo) — we’re happy to help!
{% endhint %}


# What is a Handle ID?

<figure><img src="/files/skxa9RY5eaqWv3h7tim5" alt=""><figcaption><p>Where to find a Handle in Platter+</p></figcaption></figure>

A **handle** is a unique identifier used to connect an app block (like a Platter+ extension) to your Shopify Checkout. Think of it as a label that Shopify uses to recognize and display the app block in the correct spot during checkout.

### Why are Handles useful?

Handles make the setup process seamless and reliable:

1. **Quick Installation**: Instead of manually configuring or searching for an app block, copying and pasting the handle ensures the correct extension gets added immediately.
2. **Error-Free**: Because each handle is unique, it prevents confusion or mistakes when enabling multiple checkout extensions.
3. **Flexibility**: You can easily enable, disable, or customize app blocks by pasting their handles into the Shopify Checkout Editor, giving you more control over the checkout experience.

<figure><img src="/files/o0QMlujCh8wHJB0v1nR9" alt=""><figcaption><p>Where to paste a Handle in the checkout editor</p></figcaption></figure>

### Where can I find the Handle for the extensions I have configured?

In the **Extensions** tab, you can find the Handle IDs for all of the extensions you have saved.

To save a Handle from this view, simple click the `+` icon and the Handle will be copied to your clipboard.

<figure><img src="/files/fipjbdIL48CAIWXtHTkW" alt=""><figcaption></figcaption></figure>


# What is a post-purchase page vs thank you page?

A **post-purchase page** (like Platter+'s) appears **immediately after checkout** but **before the thank you page**.&#x20;

The key benefit? Customers can accept an offer with just one click. N**o need to re-enter payment information**.

In contrast, a **thank you page** is displayed **after checkout is fully complete**. While you can promote additional products on a thank you page, customers would need to go through the friction of re-entering their payment details to make another purchase.

{% tabs %}
{% tab title="Post-purchase page" %}

<figure><img src="/files/8VmfPyiGWdbUYZP5ZOHW" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Thank you page" %}

<figure><img src="/files/WIfXyKhA9uZEmFaXlCHO" alt=""><figcaption></figcaption></figure>

{% endtab %}
{% endtabs %}

### Why does this matter?

1. **Increases revenue without disrupting checkout**: The post-purchase offer comes *after* the customer has already completed checkout, so there’s no risk of losing the original sale.
2. **Frictionless experience**: One-click post-purchase offers feel seamless. Customers don’t have to re-enter payment details, making it easier for them to say “yes” to an offer.
3. **Higher conversion rates**: With less effort required, post-purchase offers often convert better than thank you page upsells.
4. **Adds to the original order**: The post-purchase offer is added to the same transaction, simplifying order fulfillment and reducing shipping costs.

### Quick Comparison

|                                          | Post Purchase Offer Page | Thank You Page |
| ---------------------------------------- | ------------------------ | -------------- |
| Displays personalized offers             | :white\_check\_mark:     |                |
| Adds to original order                   | :white\_check\_mark:     |                |
| Increases average order value            | :white\_check\_mark:     |                |
| Doesn't require re-entering payment info | :white\_check\_mark:     |                |
| Multi-currency                           |                          |                |
| Detailed summary of order                |                          |                |


# What is an offer group?

## What is an offer group?

Offer groups are a powerful feature in Platter+ that allow merchants to deliver personalized, data-driven product recommendations to customers using the [In-Checkout Cross-Sells](/checkout/checkout-extensions/in-checkout-cross-sells) and [Post-Purchase Offers](/post-purchase/post-purchase-offers) extensions.&#x20;

## Why are offer groups useful?

Offer groups let you group products together, either manually or automatically, to make smarter product recommendations to customers.&#x20;

Traditional upsells rely on manually assigning specific products, which can lack relevance and take a lot of time.&#x20;

## **Types of offer groups**

Offer groups are created in two ways:

1. **Related Products (powered by Search & Discovery)**\
   Shopify’s AI recommends products based on the customer’s shopping behavior, purchase history, or what’s already in their cart.\
   **Example:** If a customer adds a camera, related products might include a camera lens or tripod.
2. **Complementary Products (powered by Search & Discovery)**\
   Suggest items that naturally pair with products in the customer’s cart. These recommendations are tailored to create a complete shopping experience. \
   **Example:** A customer purchasing running shoes might see recommendations for socks or a water bottle.
3. **Top Sellers (generated automatically)**\
   This group highlights your store’s best-selling products, which are automatically populated using Shopify’s sales data.
4. **Custom Group (manually created)**\
   Merchants can create their own offer group, giving you complete flexibility to upsell or cross-sell specific items. A custom offer group can be either a collection or a manually created group of products (or even just one product).\
   **Example:** Products that you'd like to offer to customers during the holidays.

## **How do offer groups work**

With offer groups, you have full control over how products are displayed in your checkout. You can:

* **Adjust hierarchy:** Set the priority of offer groups (e.g., Complementary Products first).
* **Hide groups:** Remove groups that don’t align with your goals.
* **Create new groups:** Manually add custom product collections to meet specific needs.

When the customer gets to the checkout process, Platter+ will display product offers to the customer based on the offer groups you select, and the hierarchy you set.

<figure><img src="/files/4taQ2vCcpwsIb9q0Vb3K" alt=""><figcaption><p>Example of the offer group hierarchy in the In-Checkout extension.</p></figcaption></figure>

For example, based on the settings above, the customer would see products in the cross-sell extension from the *Complementary products* group first. If there was not enough products in that group, to fill three offers that are displayed, a product from the *Related products* group would then be shown.&#x20;

This approach ensures recommendations are relevant, personalized, and more likely to drive additional purchases.


# How do I remove an extension?

Removing an extension from your checkout or Platter+ is a simple process. The steps below will walk you through how to:

* [Remove an extension from your checkout page](#remove-an-extension-from-your-checkout-page)
* [Remove Post-Purchase Offers from your post-purchase page](#remove-post-purchase-offers-from-your-post-purchase-page)
* [Delete an extension in the Platter+ app](#delete-an-extension-in-platter)

## Remove an extension from your checkout page

To stop an extension from appearing in your live checkout, you’ll need to update your settings in Shopify:

1. Log in to your Shopify Admin.
2. Navigate to your **Checkout settings** and click **`Customize`**.\
   ![](/files/wbMxf9lcbeiCErIhDZzQ)
3. Locate the app block for the extension you want to remove. Click on the ellipsis, and select **`Remove`**.\
   ![](/files/O7la3eXwOv4lsvuqg2PW)
4. **`Save`** to publish your changes.\
   ![](/files/4ZnwlX39yPbwg0XndN96)

## Remove Post-Purchase Offers from your post-purchase page

To disable a post-purchase offer from appearing after checkout:

1. Go to your **Checkout** settings in Shopify.
2. Scroll down to the **Post-purchase page** section.
3. Select **None** from the options.\
   ![](/files/HPkT4f194GTjOAIxeocS)
4. Click **Save** to apply the changes.

## **Delete an extension in Platter+**

{% hint style="warning" %}
Deleting an extension in Platter+ does not remove it from your live checkout. You must [remove an extension from your checkout page](#remove-an-extension-from-your-checkout-page) to ensure it’s no longer visible in your checkout.
{% endhint %}

If you no longer want an extension in your Platter+ app:

1. Go to **My extensions** in Platter+, located in the Extensions tab.
2. Select the extension you wish to remove.\
   ![](/files/5nyFVEGCEe9jBHRPrMFk)
3. Click **`Delete`** to remove the extension from Platter+.\
   ![](/files/oEGRAOvVuFTSHGftYwsM)


# An auto-generated offer group is not showing any products?

If an auto-generated offer group does not display, either in **Post-Purchase Offers** or **In-Checkout Cross-Sells**, it's for one of two reasons:

1. The offer group is empty.
2. There are no fallback products (a manually created offer group that ensures customers will see product offers, if all other offer groups are empty).

If this happens, we recommend creating a custom offer group and adding it to your hierarchy.

## How to create a custom offer group

1. Open the Platter+ in Shopify.
2. Go to the configuration for **In-Checkout Cross-Sells** or **Post-Purchase Offers**.\
   ![](/files/Sn1x0E3iEQFXF00bCvGM)
3. Open the settings in the **Set up your offer** module.
4. Click **`Manage groups`**.\
   ![](/files/JyegM1OPU0ltxq6NyBvT)
5. Click **`Add new group`**.\
   ![](/files/pYDKRPeWh9GadpINeD4v)
6. Name the group (e.g., "Fallback products"), select the products or collection, and **`Save changes`**.\
   ![](/files/1iH3aqxQjjPLuI0wr3TD)
7. Make sure sure to select the new custom offer group.\
   ![](/files/4EGgCtinc7TGoPxY087b)
8. Adjust the hierarchy of the offer groups.\
   ![](/files/Zm4AYfMFOLxyrg7os31Y)
9. **`Save`** your settings.\
   ![](/files/nCsUXLCZIWTZKVgmmgIz)

{% hint style="info" %}
**In-Checkout Cross-Sells** and **Post-Purchase Offers** use the same offer groups. When you create a custom group for one, it automatically becomes available in the other.
{% endhint %}


# How do I test Post-Purchase Offers?

Unlike checkout extensions, the post-purchase page **cannot be previewed** before going live. To ensure it’s working correctly, we recommend placing a test order on your store.

## Important Considerations for Testing

When creating a test order, be aware of these [limitations and consideration from Shopify](https://shopify.dev/docs/apps/build/checkout/product-offers#limitations-and-considerations). The most important to be aware of are:

* Orders need to be $0.50 or more to qualify for post-purchase offers.
* The post-purchase page won't be surfaced in the following scenarios:
  * The customer chooses to check out with an installment service or a wallet service (such as Klarna, Affirm, AfterPay, Apple Pay, Amazon Pay, or Google Pay).
  * The initial purchase was made with a gift card or any payment method other than a credit card.

## **How to Test Your Post-Purchase Offer**

1. **Create a test product** priced at **$0.50 or higher** (or use an existing product).
2. **Enable a post-purchase offer** in Platter+.
3. **Place a real order** on your store using a **credit card** (Shopify Payments or a supported gateway).
4. **Complete checkout** and confirm whether the post-purchase page appears.
5. **Check order details** in Shopify to ensure the offer was applied correctly.


# Why are the checkout extension buttons greyed out?

If the checkout extension buttons are greyed out in Platter+, it means that checkout extensions are not currently available for your store.

<figure><img src="/files/Ax4pHWpoWkYm8R2ECtJk" alt=""><figcaption></figcaption></figure>

## **Why is this happening?**

Checkout extensions require **Checkout Extensibility**, which is **only available to Shopify Plus stores**. Additionally, Platter+ checkout extensions are only accessible to merchants on the **Pro plan**.

## **How to Enable Checkout Extensions**

To use checkout extensions in Platter+, you must:

1. **Be on Shopify Plus** – Checkout Extensibility is only available for Shopify Plus stores.
2. **Upgrade to the Platter+ Pro Plan** – Checkout extensions are a Pro feature.

If your store meets these requirements and the buttons are still greyed out, try refreshing your Shopify Admin or reach out to our support team for assistance.

For more details on Shopify Plus and Checkout Extensibility, visit Shopify's official [Checkout Extensibility documentation](https://shopify.dev/docs/api/checkout-extensions).


# Tracking issues with post-purchase

## Overview

When you enable **Post-Purchase Offers** in Platter+, an additional page is added to your checkout flow—one that appears after the initial checkout, but before the thank-you page. This extra page gives brands a powerful way to increase AOV, but it can sometimes cause issues with analytics platforms like **Meta (Facebook)** and **Google Analytics**.

## What’s the issue?

Since the post-purchase page is technically separate from the thank-you page, some tracking setups (especially those using legacy or standard pixels) may not properly capture conversion events. This can result in:

* Inaccurate or missing conversion tracking in Meta Ads Manager
* Incomplete purchase funnel data in Google Analytics
* Mismatched event counts between your store and your ad platforms

## The fix: Use Shopify's custom pixels with Google Tag Manager

To make sure your conversion events fire correctly—including on the post-purchase page—you'll want to use **Shopify’s custom pixels** along with **Google Tag Manager (GTM)**.

Shopify has a full guide here > [Use Google Tag Manager with custom pixels](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels/gtm-tutorial).

***

## How to set up custom pixels with Google Tag Manager

1. **Create a Google Tag Manager container**\
   If you haven’t already, set up a GTM container for your store.
2. **Add GTM to your Shopify store using a custom pixel**
   * Go to **Shopify Admin > Settings > Customer events**
   * Click **Add custom pixel**
   * Paste the GTM code snippet into the pixel editor as shown in the [Shopify guide](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels/gtm-tutorial)
3. **Configure GTM to handle key conversion events**\
   Within your GTM workspace:
   * Create tags for platforms like Meta (Facebook Pixel) or Google Analytics
   * Set up triggers based on Shopify's custom event names like `checkout_completed`, `post_purchase_page_viewed`, etc.
   * Be sure to fire these tags not just on the thank-you page, but on any page where the conversion event could happen (like the post-purchase offer page)
4. **Test your setup**\
   Use the **Preview** mode in GTM and Shopify's **Customer Events** test mode to ensure events are firing correctly.

***

## Why this works

Using Shopify’s custom pixel framework ensures that your analytics tools can properly listen for all relevant events across the checkout flow—including on custom pages like those added by Platter+. This helps maintain accurate reporting, attribution, and campaign optimization.


# How can I track revenue generated with Platter+?


# Can I get help setting up extensions?


# Contact support

If you’re experiencing any issues or have questions about using Platter+, our team is here to help!

{% embed url="<https://calendly.com/d/cnpn-fkj-xxz/platter-support-call>" %}

You can also email us at [**hello@platter.co**](mailto:hello@platter.co) with details of your issue, and we’ll get back to you as soon as possible. Alternatively, you can use the Intercom in the lower right side of this window.


# Product feedback

Got feedback about Platter+?

We’d love to hear from you! Use the form below to share what you love (or don’t) about Platter+, bump a feature request, suggest a new topic for the Help Docs, or just send us a note. We’re all ears!

{% embed url="<https://getplatter.notion.site/14509c9be85280ab986df7359abf2660?pvs=105>" %}


# Platter Bundle Overview

### The Platter Bundle includes Smart Theme, Platter+, and white-glove onboarding.

Each purchase of the Platter Bundle includes a strategy for increasing your storefront's average order value, improving conversion, and decreasing app dependencies.

The Platter Bundle includes **Smart Theme**, our Shopify theme, and **Platter+**, our Shopify app, along with:

1. Conversion rate optimized theme and app configuration
2. Order value optimized theme and app configuration
3. 3rd party application audit


# Smart Theme Overview

Smart Theme is our flexible and feature-rich Shopify theme, built to increase conversion rate and average order value.

Browse the below categories to quickly find what you're looking for.

## Theme Settings

{% content-ref url="/pages/GX1D5tHvMayawSVyVsgW" %}
[Logo Imports](/smart-theme/theme-settings/logo-imports)
{% endcontent-ref %}

{% content-ref url="/pages/vbInHRF8AotlQQF5gkft" %}
[Layout](/smart-theme/theme-settings/layout)
{% endcontent-ref %}

{% content-ref url="/pages/ZSayuGt0OCPm47GJznxC" %}
[Color Groups](/smart-theme/theme-settings/color-groups)
{% endcontent-ref %}

{% content-ref url="/pages/jBO5rhL8vJX7NV67Z5o2" %}
[Fonts & Typography](/smart-theme/theme-settings/fonts-and-typography)
{% endcontent-ref %}

## Shopify Insights

{% content-ref url="/pages/bKPRKMEEONT3WU7QCv96" %}
[Online Store 2.0](/smart-theme/shopify-insights/online-store-2.0)
{% endcontent-ref %}

{% content-ref url="/pages/4c9xSfsZ9CQ2J4JoSINX" %}
[Shopify's Search & Discovery App](/smart-theme/shopify-insights/shopifys-search-and-discovery-app)
{% endcontent-ref %}

{% content-ref url="/pages/RXYgGmVOZSpIZ7YCnmdX" %}
[Metafields, Custom Data, and the Shopify CMS](/smart-theme/shopify-insights/metafields-custom-data-and-the-shopify-cms)
{% endcontent-ref %}

## Important Pages, Sections, and Components

{% content-ref url="/pages/bslVNzryTJJJPZIlbkFt" %}
[Cart Drawer](/smart-theme/structural-components/cart-drawer)
{% endcontent-ref %}

{% content-ref url="/pages/knXpFJWsJ31PAwvdbfGG" %}
[Quick View](/smart-theme/structural-components/quick-view)
{% endcontent-ref %}

{% content-ref url="/pages/fmIUxt1juVyjpwRVdjYI" %}
[Navigation & Mega Menu](/smart-theme/structural-components/navigation-and-mega-menu)
{% endcontent-ref %}

{% content-ref url="/pages/KFcUUVk0omTpDMreRV6o" %}
[Footer](/smart-theme/structural-components/footer)
{% endcontent-ref %}


# Sections


# Email Capture

Ensure your customers are subscribed to your comms.

Customers who submit their email addresses in a newsletter section or component will be stored under the `Customers` section of your Shopify backend.&#x20;

If a customer account associated with the email address already exists, that customer account will be marked as `Email subscribed` under **Marketing** and tagged with `newsletter`.

<figure><img src="/files/qwlylYa5kf2H5AWfEIOU" alt=""><figcaption></figcaption></figure>


# FAQ Section

Create FAQ groups to fit lots of information into a small amount of space.

{% embed url="<https://www.loom.com/share/e74f57f42f1a4eedad86c12f7b8f372c>" %}


# Image Banner

Our image banner section is hyper-flexible.

Highlights include:

1. Image overlay
2. Multiple sources -> Image, video via upload, or video via YouTube or Vimeo URL&#x20;
3. Vertical and horizontal alignment options

A few examples below.&#x20;

{% embed url="<https://www.figma.com/file/rO1PDa8fmvob2Z36nP4l4l/Design-System-V2?node-id=1399:10257&t=wNzoRMmCqQVADi2H-1&type=design>" %}


# Instagram Feed

Simulate tagged images to drive purchases.

Available under `Sections > Tagged Product Images`

{% embed url="<https://www.figma.com/file/rO1PDa8fmvob2Z36nP4l4l/Design-System-V2?node-id=2415:13223&t=GywCg0EQyWJbkSWi-1&type=design>" %}

<div align="left"><figure><img src="/files/8Ni6a4vEZV4w2viQULwH" alt=""><figcaption></figcaption></figure></div>


# Recently Viewed

Display products that were recently viewed by the customer.

Please review the below Loom for how to configure our 'Recently Viewed Products' section.&#x20;

{% embed url="<https://www.loom.com/share/92b53bf426de4909b490adeffd928420>" %}


# Upsells

Upsells are the best way to increase average order value on your storefront without increasing pricing.

{% hint style="success" %}
In-checkout and post-purchase upsells are available through our app, **Platter+**, and are not documented below. The following is specific to Smart Theme.
{% endhint %}

## Product Detail Page

Watch the below tutorial for an in-depth explanation of how to add upsells and cross-sells within the Buy Box on your product detail page.

{% embed url="<https://www.loom.com/share/58089a95fd844463964e2c05afe1c54b?sid=45e95959-27f0-4dd1-b878-b460c05dd32b>" %}

Watch the below tutorial for an in-depth explanation of how to add upsells and cross-sells below the fold on your product detail page.

{% embed url="<https://www.loom.com/share/92b53bf426de4909b490adeffd928420?sid=9df98c94-d6c8-4061-8449-e29eef822821>" %}

## Cart Drawer

Watch the below tutorial for an in-depth explanation of how to add upsells and cross-sells within your cart drawer.

{% embed url="<https://www.loom.com/share/3c16b28b913749ecac6ab1cd685e2fe4?sid=ab88695f-320d-4d35-89fe-b3816cae16da>" %}


# Products


# Product Page Blocks

Click into each of the below pages to learn more about available Product Page blocks.


# Color Swatches

Let customers pick products in different colors. This includes product variants and sibling products.

### Standard Swatches

Standard swatches are used for variants of the same product, and can be powered by images or hex codes. To configure them:

1. Navigate to your product page and ensure `Product > Variant Selector > Use Color Selector` is checked.

{% embed url="<https://www.loom.com/share/ccf36a98308b437b8f8ee669db8274b8>" %}

2. Add the swatch hex code or image URL to `assets/swatches.json`

{% embed url="<https://www.loom.com/share/a1e3a3b46f0d42c19362644e132ab055>" %}

### Sibling Products

Sibling products are used to display color swatches for multiple different products as if they are variants of the same product.&#x20;

Clicking through the swatches will navigate the user to a different product page, but there is no load time so the experience is as smooth as switching between variants.

The steps outlined in the below walkthrough are:

1. Create the relevant metafields
2. Populate the metafields
3. Add the Sibling Products section and block to your product detail page
4. Test the settings and determine what's best for your store

{% embed url="<https://www.loom.com/share/d231d54970844616b4858102a2f21c0d>" %}


# Pre-Order

Accept orders in advance for upcoming products or shipments.

{% embed url="<https://www.loom.com/share/31441774e92a45dea521f7a71e99fa38>" %}


# Stock Counter

Display how much stock remains for a product.

{% embed url="<https://www.loom.com/share/77a6c191f5094141a20d6aee13991ad7>" %}


# Complementary Products

This block is sometimes referred to as 'Complete the look' or 'Pairs well with'.

Review the below to learn how to place complementary products on your product page.&#x20;

{% embed url="<https://www.loom.com/share/58089a95fd844463964e2c05afe1c54b>" %}


# Product Pages


# Multiple Variant Images

Associate more than one image to a product variant.

## Variants of the same product

{% embed url="<https://www.loom.com/share/a93418f4a0a148de9a3b529188b01e16>" %}

## Sibling products

Sibling product configuration is covered under Color Swatches.

{% content-ref url="/pages/1ILOvEx0bBcotpcbZupS" %}
[Color Swatches](/smart-theme/products/product-page-blocks/color-swatches)
{% endcontent-ref %}


# You May Also Like

Suggest products to customers based on what other customers have purchased together.

The below explains how to configure our 'You May Also Like' section on your Product Pages. To configure upsells in other ways, see the [Upsells and Cross-Sells section](broken://pages/lSDIXKiczb2UPXTiO1FI) of our docs.

{% embed url="<https://www.loom.com/share/92b53bf426de4909b490adeffd928420>" %}


# Quick View

Allow customers to quickly view more detail about a product without leaving the page.

{% hint style="info" %}
The below is only applicable to Smart Theme versions 2.1.0 and below.
{% endhint %}

Configure your quick view using the **Quick View** setting located above your section selector. Watch the below tutorial for a more in-depth explanation.

{% embed url="<https://www.loom.com/share/cf8263e2049a4cdab390963f72e08e7d>" %}


# Product Cards

Control the level of information featured on your cards.

Navigate to `Theme Settings > Product Cards` or `Theme Settings > Article Cards` to adjust the level of information shown on your cards, such as toggling review star visibility. The changes made here will cascade throughout all card instances.

### Product Badges

Product badges allow you to display 'Sale', percentage off, dollar amount off, or custom messaging. Product badges are managed within `Theme Settings > Product Card > Label`

Click below for more detail on custom badges, including custom colors.

{% content-ref url="/pages/EO0npaCiJ1Hqew6F2QIl" %}
[Custom Product Badges](/smart-theme/products/product-cards/custom-product-badges)
{% endcontent-ref %}

### Mockup

{% embed url="<https://www.figma.com/file/rO1PDa8fmvob2Z36nP4l4l/Design-System-V2?node-id=2955:9281&t=uIGzAQAX8LgYw329-1&type=design>" %}


# Custom Product Badges

Theme versions 2.4.10 and upwards support custom colors for your product badges via metaobjects. Follow the below steps to set them up.

#### Step 1: Create a `Label`metaobject.

Include the following attributes.

1. Label Text -> `label.label_text`
2. Text Color -> `label.color`
3. Background Color -> `label.background_color`

<div align="left"><figure><img src="/files/PDHt58JBuaTOKcku1Sac" alt=""><figcaption></figcaption></figure></div>

#### Step 2: Link the metaobject to a Product metafield

Create a product metafield called `Labels` and ensure its namespace is `smart.labels`

The new Label metafield should be a list of type Mixed Reference. The metafield should reference the new `Label` metaobject that you created in step 1.&#x20;

<div align="left"><figure><img src="/files/yQn8tvuMddMz8C1zEX2T" alt=""><figcaption></figcaption></figure></div>

#### Step 3: Populate the metaobject for the desired product(s)

Navigate to the Products section of your Shopify backend and populate the metaobject that you created.&#x20;

<div align="left"><figure><img src="/files/TeWZrA9lSXuUVMznpnyt" alt=""><figcaption><p>Add a label entry</p></figcaption></figure></div>

<div align="left"><figure><img src="/files/TK6ibJdQlNR5ogWjbtlt" alt=""><figcaption><p>Populate a label</p></figcaption></figure></div>

#### Step 4: Check that it works!&#x20;

You should see a custom badge (or list of badges) on your product cards.&#x20;

![](/files/UzoleNq2gc9uOdChAosp)


# Collection Page


# Collection Page Filters

Filters are powered by Shopify's Search & Discovery app. Click below to learn more.&#x20;

{% content-ref url="/pages/4c9xSfsZ9CQ2J4JoSINX" %}
[Shopify's Search & Discovery App](/smart-theme/shopify-insights/shopifys-search-and-discovery-app)
{% endcontent-ref %}


# Pages


# Page Templates

The following walks through how to build out page templates using Smart Theme theme. Visit [Layout](/smart-theme/theme-settings/layout) and [Color Groups](/smart-theme/theme-settings/color-groups) for more information related to configuring each section.&#x20;

{% embed url="<https://www.loom.com/share/fbf74bfceb864c16ad58859975102c39>" %}


# Updating Your Theme


# Check Your Theme Version

To check your theme version, navigate to `Online Store > Themes`. Your version is noted beneath the name of each theme. Screenshot below for reference.

<figure><img src="/files/pD8bxF5wbF0McO5E8xvh" alt=""><figcaption></figcaption></figure>


# Upgrade Your Theme Version

Theme version upgrades are included with your Platter subscription when:

1. The theme's codebase is unmodified.
2. The theme's codebase is modified, but the modifications were performed by the Platter team.

If you meet either of the above criteria, please reach out to <help@platter.co> to request an upgrade.


# Change Log

<details>

<summary>v2.4.6 -> May 5th, 2023</summary>

#### New

* Search bar upgrades

#### Updated

* Swatches color selection option

#### Fixed

* You May Also Like in the cart drawer doesn't go away when 'Enable recommended products' is not selected
* Products with only one color variant don't show variant selectors
* Rich text is reverted to not respecting spacing between paragraphs
* 'White' color swatches are not visible on white backgrounds
* Wrong color shows on collection page. Seems to be related to the variant issue, unless it's coincidental that the variant issue also occurs for this product
* Route protection product doesn't show on the cart page

</details>


# Blogs & Blog Posts

Blogs consist of Blog Posts. You can have multiple blogs on your store.


# Blog Posts


# Shop-able Blog Posts

This features allows you to place relevant products on your blog posts.

Navigate to `Blog Posts` to configure.

{% embed url="<https://www.loom.com/share/593ab1f17b1c4954b34bd65cd5b2e264>" %}


# Theme Settings

Browse important theme settings below.


# Logo Imports

Import your light on dark and dark on light logotypes.

Smart accepts 2 logos, one for use on dark backgrounds and one for use on light backgrounds. Any section that accepts a logo, such as your footer, will allow you to select the one you want to use.&#x20;

Navigate to `Theme Settings > Branding` to import your logos.&#x20;


# Layout

Granular whitespace control without needing to write a single line of code.

To edit your layout settings, navigate to `Theme Settings > Layout`. There you're able to control grid width and section padding.

Each section contains `Top Padding` and `Bottom Padding` settings, which control the amount of whitespace above and below the section.

<figure><img src="/files/kDUTpcjkgPUQd7hsKFau" alt=""><figcaption></figcaption></figure>


# Color Groups

Color groups are set at the theme level and applied at the section level.

Navigate to `Theme Settings` and you will see Color Groups 1 through 5. Change the colors within the group to align with your brand, and then apply the groups at the section level.

Review the below, where we:

1. Identify the color group in-use for a section
2. Change a part of the section, in this case the button text color

{% embed url="<https://www.loom.com/share/a72dd3ad6e2f4d8da5df34448bbbb61a>" %}


# Fonts & Typography

Make up to 5 fonts available to your theme, including Google Fonts.

Smart is the only theme that natively supports the level of font granularity typically associated with design tools such as Figma.&#x20;

1. Import the fonts you want to use in your theme via `Theme Settings > Font Imports`
2. Assign the font to a Typography group via `Theme Settings > Typography Group 1/2/3`
3. Use your imported font in a section and adjust granular details such as:
   * Desktop and mobile sizes
   * Kerning
   * Line height
   * Weight
   * Opacity&#x20;
   * Style -> `Bold`, `Italic`, or `Normal`

### Shopify fonts

Watch the below tutorial to learn how to import Shopify fonts and edit their settings within the theme.

{% embed url="<https://www.loom.com/share/a6201156f7da4b7db7a119a4f612c77f>" %}

### Google fonts and custom fonts

Watch the below tutorial to learn how to import Google fonts and edit their settings within the theme.

{% embed url="<https://www.loom.com/share/14df489cef944f8d90daf57917b457d2>" %}


# Icons

The following icon codes are available to be embedded across Rich Text sections and buttons.

* `[icon.5-stars-i]`
* `[icon.5-stars]`
* `[icon.filters]`
* `[icon.hamburger]`
* `[icon.printer]`
* `[icon.cart]`
* `[icon.link]`
* `[icon.link-external]`
* `[icon.warning]`
* `[icon.warning-triangle]`
* `[icon.timer]`
* `[icon.arrow-right-circle]`
* `[icon.arrow-right]`
* `[icon.arrow-left]`
* `[icon.chevron-up-down]`
* `[icon.check-mark]`
* `[icon.check-mark-circle]`
* `[icon.x-close-circle]`
* `[icon.x-mark]`
* `[icon.triangle]`
* `[icon.twitter]`
* `[icon.facebook]`
* `[icon.pinterest]`
* `[icon.instagram]`
* `[icon.tiktok]`
* `[icon.tumblr]`
* `[icon.snapchat]`
* `[icon.youtube]`
* `[icon.vimeo]`
* `[icon.email]`
* `[icon.password-eye]`
* `[icon.password-eye-slash]`
* `[icon.activity]`
* `[icon.alert-circle]`
* `[icon.announcement]`
* `[icon.arrow-narrow-left]`
* `[icon.arrow-narrow-right]`
* `[icon.at-sign]`
* `[icon.bookmark-add]`
* `[icon.bookmark-check]`
* `[icon.building-large]`
* `[icon.building]`
* `[icon.calendar]`
* `[icon.check-circle-broken]`
* `[icon.check-circle]`
* `[icon.check-heart]`
* `[icon.check-square-broken]`
* `[icon.check-square]`
* `[icon.check]`
* `[icon.chevron-down]`
* `[icon.chevron-left]`
* `[icon.chevron-right]`
* `[icon.chevron-selector-vertical]`
* `[icon.chevron-up]`
* `[icon.clock]`
* `[icon.cloud-blank]`
* `[icon.credit-card]`
* `[icon.currency-dollar-circle]`
* `[icon.face-happy]`
* `[icon.face-neutral]`
* `[icon.face-sad]`
* `[icon.face-smile]`
* `[icon.globe]`
* `[icon.heart-hand]`
* `[icon.heart]`
* `[icon.help-circle]`
* `[icon.home]`
* `[icon.image]`
* `[icon.info-circle]`
* `[icon.lock]`
* `[icon.marker-pin]`
* `[icon.menu]`
* `[icon.minus-circle]`
* `[icon.minus-square]`
* `[icon.minus]`
* `[icon.percent-circle]`
* `[icon.percent]`
* `[icon.pin]`
* `[icon.plane]`
* `[icon.plus-circle]`
* `[icon.plus-square]`
* `[icon.plus]`
* `[icon.puzzle-piece]`
* `[icon.rocket]`
* `[icon.search]`
* `[icon.share]`
* `[icon.shopping-bag]`
* `[icon.shopping-cart]`
* `[icon.star]`
* `[icon.tag]`
* `[icon.thumbs-up]`
* `[icon.tool]`
* `[icon.truck]`
* `[icon.user]`
* `[icon.x-circle]`
* `[icon.x-close]`
* `[icon.zap]`


# Structural Components

Here are a few Platter Base highlights.


# Header


# Announcement Bar

{% embed url="<https://www.loom.com/share/17162ca5b3ba41f58b4b55992384e7f8?sid=e9fe018b-201e-47e4-a5cd-e32f63c3619f>" %}


# Free Shipping Progress Bar

{% embed url="<https://www.loom.com/share/17162ca5b3ba41f58b4b55992384e7f8?sid=32b07df6-3f98-4ed9-bee9-3dd81db6d0f8>" %}


# Navigation & Mega Menu

Click the below link for a configuration tutorial.

{% hint style="danger" %}
**The following tutorial applies only to theme versions 2.4.9 and up**
{% endhint %}

### **How to configure your mega menu on desktop**

{% embed url="<https://www.loom.com/share/683b5fbac50c4947aed5415c1156fd68?sid=22b93680-1dd2-40d6-b17d-6193d2f035d5>" %}

{% hint style="danger" %}
**The following tutorial applies only to theme Versions 2.0.0 through 2.2.20**&#x20;
{% endhint %}

{% embed url="<https://www.loom.com/share/9d0ae53b93754cc1a05e4920bb6e9257>" %}


# Cart Drawer

You cart drawer is a powerful tool for increasing conversion rate. It allows your customers to initiate checkout without needing to visit the cart page.

Smart's cart drawer includes the following features.

1. An incentive progress bar
2. An announcement bar
3. Multiple 'Empty State' options for when there are no products in the user's cart
4. In-cart upsells and cross-sells
5. An on/off toggle for insurance and/or route protection
6. A checkbox for specifying whether an order is a gift
7. An order note input

Review the below tutorial to learn how to configure your Cart Drawer.&#x20;

{% embed url="<https://www.loom.com/share/3c16b28b913749ecac6ab1cd685e2fe4?sid=08973fb4-436a-4fec-829e-60d975282cdc>" %}

Consult the below for component-specific information.

{% content-ref url="/pages/p9oJmoYbOXhf1YMz5hoC" %}
[Gift with Purchase](/smart-theme/structural-components/cart-drawer/gift-with-purchase)
{% endcontent-ref %}

{% content-ref url="/pages/RmHIpRb4MEBpt3tTr93O" %}
[Gift Wrapping](/smart-theme/structural-components/cart-drawer/gift-wrapping)
{% endcontent-ref %}

{% content-ref url="/pages/bhJMnsEkvZDUI9vnWX9w" %}
[Free Shipping Progress Bar](/smart-theme/structural-components/cart-drawer/free-shipping-progress-bar)
{% endcontent-ref %}


# Gift with Purchase

The below tutorial outlines how to configure Gift with Purchase.

{% embed url="<https://www.loom.com/share/8b8231fcf9dc4f0e977ad2e607c5ead5?sid=abff8f49-47c0-444f-8303-2925ab248b24>" %}


# Gift Wrapping

Let customers mark an item as a gift, and optionally allow them to leave a note.

{% embed url="<https://www.loom.com/share/f232a83e014e4155945f00f182fb9e36>" %}


# Free Shipping Progress Bar

Visualize your customer's progress towards an incentive.

How to configure your announcement bar and incentive progress bar.

{% embed url="<https://www.loom.com/share/17162ca5b3ba41f58b4b55992384e7f8>" %}
How to configure your announcement bar and incentive progress bar
{% endembed %}


# Landing Page Builder Integrations

The below code snippets outline how to trigger Cart Drawer events from your landing page builder, e.g. Replo.

The following window event will add an item to the user's cart and open the cart drawer.

```
window.cart.add(input:  {
  items: {
    id: number | string;
    quantity: number;
    properties?: {
      [T: string]: string;
    };
    selling_plan?: number;
  }[];
  attributes?: {
    [T: string]: string;
  };
}, boolean)
```

Here's an example usage. The second parameter, set here to `true`, dictates whether the cart drawer will open. To add a product to the user's cart without opening the cart drawer, set the second parameter to `false`.

```
window.cart.add({ items: [{
  id: 12345678, // variant_id
  quantity: 1
}]}, true)
```


# Quick View

Quick View allows your customers to view more information about a product without leaving the page.

{% embed url="<https://www.figma.com/file/rO1PDa8fmvob2Z36nP4l4l/Design-System-V2?node-id=3522:11511&t=KMWFlXSOr4eRoQyq-1&type=design>" %}


# Footer

Capture emails, feature extensive links, and display social media icons.

The footer accepts multiple link blocks. Top-level navigation menu items are displayed as column headers.

{% embed url="<https://www.loom.com/share/016fbd7c4926428aac2637dd40c09a7c>" %}


# Accounts and Login

Smart supports Classic Customer Accounts, but New Customer Accounts are recommended.

`Classic customer accounts` are handled within the theme, and Smart supports customization of the following pages.

* Customer login
* Customer register
* Customer order
* Customer addresses
* Customer account
* Customer reset password

However, we recommend upgrading to `New customer accounts`. Shopify's documentation on customer accounts is below.

{% embed url="<https://help.shopify.com/en/manual/customers/customer-accounts>" %}

The below demonstrates how to access `Classic customer accounts` within the theme.

<figure><img src="/files/ElY5i8tI1HoY3m2Dekqy" alt=""><figcaption></figcaption></figure>


# Shopify Insights

These Shopify insights are not specific to Platter Base, but they can help you make the most of it.

{% content-ref url="/pages/bKPRKMEEONT3WU7QCv96" %}
[Online Store 2.0](/smart-theme/shopify-insights/online-store-2.0)
{% endcontent-ref %}

{% content-ref url="/pages/4c9xSfsZ9CQ2J4JoSINX" %}
[Shopify's Search & Discovery App](/smart-theme/shopify-insights/shopifys-search-and-discovery-app)
{% endcontent-ref %}

{% content-ref url="/pages/RXYgGmVOZSpIZ7YCnmdX" %}
[Metafields, Custom Data, and the Shopify CMS](/smart-theme/shopify-insights/metafields-custom-data-and-the-shopify-cms)
{% endcontent-ref %}


# Online Store 2.0

## How OS 2.0 works and why it matters

Shopify's Online Store 2.0 theme architecture introduces [sections on every page](broken://pages/7Umjc1NYuNzjs55sImxV), theme app extensions, greatly improved [custom data](/smart-theme/shopify-insights/metafields-custom-data-and-the-shopify-cms), and improved performance and speed.&#x20;

Now merchants (like you) and developers (like us) are able to create more unique online stores that stand out from the competition, without the custom development overhead that typically slowed store iteration during Shopify's early years.

**Smart is an Online Store 2.0 theme.**

## Helpful articles from Shopify

{% embed url="<https://www.shopify.com/partners/blog/shopify-online-store>" %}
Shopify's OS 2.0 announcement
{% endembed %}

{% embed url="<https://shopify.dev/docs/themes/os20>" %}
The official documentation
{% endembed %}


# Shopify's Search & Discovery App

Power product boosts, synonyms, and filters.

### How to use the app with Smart theme&#x20;

The following walkthrough covers search, filters, and recommendations.

{% embed url="<https://www.loom.com/share/5615d557146f4a4b917949e96ac44ec9>" %}

### Download the app below

{% embed url="<https://apps.shopify.com/search-and-discovery>" %}


# Metafields, Custom Data, and the Shopify CMS

Custom data, formerly called metafields, are a powerful feature from Shopify for supercharging your storefront.

The below walkthrough covers how to create and edit custom data, including how to bulk edit.

{% embed url="<https://www.loom.com/share/0e75fb8a9b894dc88990703d164a66e5>" %}


# For Developers

Smart Theme is written in TypeScript and Tailwind CSS. Getting started is easy.


# Tech Stack

Development on Platter Base requires prior knowledge of the below tech stack, along with all of the listed developer tools.

### Tech Stack

* Web Basics -> `HTML`, `CSS`, `JavaScript`
* [Liquid](https://shopify.github.io/liquid/)
* [TypeScript](https://www.typescriptlang.org/)
  * Vanilla JS
  * [Preact](https://preactjs.com/)
  * [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction) for global state management
* [Tailwind CSS](https://tailwindcss.com/)

### **Required Developer Tools**

* [NodeJS](https://nodejs.org/en)
* [esbuild](https://esbuild.github.io/)
* [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)
* [Shopify CLI](https://shopify.dev/docs/themes/tools/cli/install)

### Use of the Accelerated Developer Tools also requires a thorough understanding of the following.

* [Shopify Theme Architecture](https://shopify.dev/docs/themes/architecture) (including all subsections)
* [Shopify Section input types](https://shopify.dev/docs/themes/architecture/settings/input-settings)
* Performance Best Practices
* [Semantic HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Cheatsheet)&#x20;
  * The best example of semantic HTML we've seen is on [stripe.com](https://stripe.com). Review their source code by inspecting the page on Chrome Dev Tools. You will see a strict adherence to \<section> \<header> \<main> \<footer> tags.
* [Accessibility Best Practices](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/CSS_and_JavaScript)


# File Structure

Review Platter Base's file structure before getting started.

## File Structure

### `./@types`&#x20;

TypeScript types for Shopify theme settings, sections, and section inputs. These are mostly auto-generated according to the global type declaration in `./@types/types.d.ts`. This applies to anything that binds to the `window` object and to small help types.

### `./assets`&#x20;

These are a local version of the theme's `./asset` folder, which that are one-way synced into the working theme as set by the env variable: `SHOPIFY_THEME_FOLDER` .&#x20;

This method of syncing ensures that individual store's themes can have their own assets, and that only files that are part of `Platter Base` are upgraded when running the dev tools. The files in the `./asset` folder are split into 3 categories:

#### Integrated Developer Tools&#x20;

These are all the config files that get loaded into the theme, to allow merchants run the integrated dev tools on their own machines.

#### TypeScript & TailwindCSS&#x20;

These files are the source files for specific section / global functionality throughout the theme. If a file relates back to only a specific section / block, the file convention is `{section_name}.{block_name}.tsx`.&#x20;

If a TS file is responsible to `render` entire components, it is important to check if server side rendering via a related `.liquid` file is necessary.&#x20;

Static server side rendering should generally be implemented first, with identical classes to ensure that there is no Cumulative Layout Shift on page load.

#### Compiled & Auto Generated&#x20;

These files include the `theme.js`, `_types.d.ts`, and `tailwind.css.liquid`, which are auto generated by the 3 different dev tools: `esbuild`, `shopify-theme-dev`, and `tailwindcss`

### `./globals`

#### `./globals/settings_schema.ts`

These are the global theme settings that are editable in the Theme Editor. These settings are transpiled via the `shopify-theme-dev` package.

#### `./globals/settings`&#x20;

These are helper files to load theme and section settings into many different areas at once, making it possible to easily repeat settings in different places.&#x20;

These files get only accessed by the `settings_schema.ts` and any `./sections/{section_name}/schema.ts`

#### `./globals/layouts`&#x20;

The `theme.liquid` file is the root entry point for Shopify files.&#x20;

It is extremely common for Apps and Merchants to make changes to their own `/layouts/theme.liquid` file, and generally this file gets excluded from upgrades and should be manually upgraded.&#x20;

The env variable `SHOPIFY_CMS_IGNORE_LAYOUTS=theme.liquid` blocks automatic updates. Removing the env variable will enable overriding the `theme.liquid`

#### `./globals/snippets`&#x20;

Snippets are helper files to render repeated layouts. There are generally 2 types of files in the folder that have different meanings by their filename. Files starting with `_` are global helper utils that are not responsible to generate any visual layout. They are small helpers to properly load images or icons and any specific data models. The other files are global layouts that are accessible within any area of the theme via {% render %} tags. Block scoped snippets should be in their related `sections` folder and not here.

### `./sections`&#x20;

These are all the Shopify sections in the theme, organized on a per folder per section basis. Each folder name should be in `kebab-case` as it provides the name for the section.&#x20;

{% hint style="success" %}
Naming of sections and the content of the `schema.ts` need to be 100% accurate to work with the dev tools.&#x20;
{% endhint %}

{% hint style="info" %}
Section names should be semantic with regards to what they do, as well as in relation to the Figma theme naming convention.&#x20;
{% endhint %}

{% hint style="danger" %}
Once a name has been set and used in multiple stores, it is not possible to change the name as it would break backwards compatibility.
{% endhint %}

#### `./schema.ts`&#x20;

This is the starting point for any section, and it contains all settings that will be available within the settings in the Theme Editor.

For a section named `side-by-side-image`, for example, the entry file would be `./sections/side-by-side-image/schema.ts`

```javascript
import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by Side Image", // This is what Shows in the Theme Editor on the Left, if the section has no setting with the id `title`
  settings: [],
	blocks: [],
  presets: [
    {
      name: "Side by Side Image", // This shows in the Theme editor when Searching for the Section when adding a new one.
    },
  ],
};
```

{% hint style="info" %}
If any of the bold and underlined names are not exact as per the naming conventions based on the filename, the dev tools will not work.
{% endhint %}

Once the new section is created, you can add `settings` and `blocks` and any other valid property as per the [Shopify section input types](https://shopify.dev/docs/themes/architecture/settings/input-settings) and [section architecture](https://shopify.dev/docs/themes/architecture/sections/section-schema).&#x20;

The `shopify-theme-dev` script will auto generate the `side-by-side-image.liquid` file and any block file as `side-by-side-image.{block_type}.liquid` .&#x20;

Any changes on the settings for the Section or Blocks, will auto generate the variables on the top of either file.&#x20;

You can also opt out of auto generating the block-level files by adding the top level property **`generate_block_files:`**` ``["block_type_to_autogenerate"]` or **`generate_block_files:`**` ``[]`&#x20;

```javascript
import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by side image",
  generate_block_files: ["image"], // Only the `image` Block will be generated as `side-by-side-image.image.liquid, Set to [] and no block files will be created  
  settings: [],
  blocks: [
    {
      type: "image",
      name: "Image",
      settings: [],
    },
    {
      type: "text",
      name: "Text",
      settings: [],
    },
  ],
  presets: [
    {
      name: "Side by side image",
    },
  ],
};
```

#### `./{section_name}.liquid`

This is the root Liquid file for any section, which get compiled together with the `./schema.ts` based on the env vairables `SHOPIFY_THEME_FOLDER/sections`, by the `shopify-theme-dev` package.&#x20;

The variables and types from the schema will be auto generated on top of the file.

```liquid
{%- comment -%} Auto Generated Variables start {%- endcomment -%}
{%- liquid
  ...
  assign title = section.settings.title
  ...
-%}
{%- comment -%} Auto Generated Variables end {%- endcomment -%}
```

#### `./{section_name}.{block_type}.liquid`

These are files each section block and get copied over into the `SHOPIFY_THEME_FOLDER/snippets` folder.

Any `*.liquid` file also accepts auto translations that are generated for JS and Shopify’s `locales/en.default.json` by placing text content in a special tag.

For example, "Add to Cart" becomes `{{ "product_card.add_to" | t }}` and `window.translations.product_card.add_to = "Add to Cart";` via the `translations.liquid` snippet.

### `./@types`&#x20;

TypeScript types for Shopify theme settings, sections, and section inputs. These are mostly auto-generated according to the global type declaration in `./@types/types.d.ts`. This applies to anything that binds to the `window` object and to small help types.

### `./assets`&#x20;

These are a local version of the theme's `./asset` folder, which that are one-way synced into the working theme as set by the env variable: `SHOPIFY_THEME_FOLDER` .&#x20;

This method of syncing ensures that individual store's themes can have their own assets, and that only files that are part of `Platter Base` are upgraded when running the dev tools. The files in the `./asset` folder are split into 3 categories:

#### TypeScript & TailwindCSS&#x20;

These files are the source files for specific section / global functionality throughout the theme. If a file relates back to only a specific section / block, the file convention is `{section_name}.{block_name}.tsx`.&#x20;

If a TS file is responsible to `render` entire components, it is important to check if server side rendering via a related `.liquid` file is necessary.&#x20;

Static server side rendering should generally be implemented first, with identical classes to ensure that there is no Cumulative Layout Shift on page load.

#### Compiled & Auto Generated&#x20;

These files include the `theme.js`, `_types.d.ts`, and `tailwind.css.liquid`, which are auto generated by the 3 different dev tools: `esbuild`, `shopify-theme-dev`, and `tailwindcss`

### `./globals`

#### `./globals/settings_schema.ts`

These are the global theme settings that are editable in the Theme Editor. These settings are transpiled via the `shopify-theme-dev` package.

#### `./globals/settings`&#x20;

These are helper files to load theme and section settings into many different areas at once, making it possible to easily repeat settings in different places.&#x20;

These files get only accessed by the `settings_schema.ts` and any `./sections/{section_name}/schema.ts`

#### `./globals/layouts`&#x20;

The `theme.liquid` file is the root entry point for Shopify files.&#x20;

It is extremely common for Apps and Merchants to make changes to their own `/layouts/theme.liquid` file, and generally this file gets excluded from upgrades and should be manually upgraded.&#x20;

The env variable `SHOPIFY_CMS_IGNORE_LAYOUTS=theme.liquid` blocks automatic updates. Removing the env variable will enable overriding the `theme.liquid`

#### `./globals/snippets`&#x20;

Snippets are helper files to render repeated layouts. There are generally 2 types of files in the folder that have different meanings by their filename. Files starting with `_` are global helper utils that are not responsible to generate any visual layout. They are small helpers to properly load images or icons and any specific data models. The other files are global layouts that are accessible within any area of the theme via {% render %} tags. Block scoped snippets should be in their related `sections` folder and not here.

### `./sections`&#x20;

These are all the Shopify sections in the theme, organized on a per folder per section basis. Each folder name should be in `kebab-case` as it provides the name for the section.&#x20;

{% hint style="success" %}
Naming of sections and the content of the `schema.ts` need to be 100% accurate to work with the dev tools.&#x20;
{% endhint %}

{% hint style="info" %}
Section names should be semantic with regards to what they do, as well as in relation to the Figma theme naming convention.&#x20;
{% endhint %}

{% hint style="danger" %}
Once a name has been set and used in multiple stores, it is not possible to change the name as it would break backwards compatibility.
{% endhint %}

#### `./schema.ts`&#x20;

This is the starting point for any section, and it contains all settings that will be available within the settings in the Theme Editor.

For a section named `side-by-side-image`, for example, the entry file would be `./sections/side-by-side-image/schema.ts`

```javascript
import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by Side Image", // This is what Shows in the Theme Editor on the Left, if the section has no setting with the id `title`
  settings: [],
	blocks: [],
  presets: [
    {
      name: "Side by Side Image", // This shows in the Theme editor when Searching for the Section when adding a new one.
    },
  ],
};
```

{% hint style="info" %}
If any of the bold and underlined names are not exact as per the naming conventions based on the filename, the dev tools will not work.
{% endhint %}

Once the new section is created, you can add `settings` and `blocks` and any other valid property as per the [Shopify section input types](https://shopify.dev/docs/themes/architecture/settings/input-settings) and [section architecture](https://shopify.dev/docs/themes/architecture/sections/section-schema).&#x20;

The `shopify-theme-dev` script will auto generate the `side-by-side-image.liquid` file and any block file as `side-by-side-image.{block_type}.liquid` .&#x20;

Any changes on the settings for the Section or Blocks, will auto generate the variables on the top of either file.&#x20;

You can also opt out of auto generating the block-level files by adding the top level property **`generate_block_files:`**` ``["block_type_to_autogenerate"]` or **`generate_block_files:`**` ``[]`&#x20;

```javascript
import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by side image",
  generate_block_files: ["image"], // Only the `image` Block will be generated as `side-by-side-image.image.liquid, Set to [] and no block files will be created  
  settings: [],
  blocks: [
    {
      type: "image",
      name: "Image",
      settings: [],
    },
    {
      type: "text",
      name: "Text",
      settings: [],
    },
  ],
  presets: [
    {
      name: "Side by side image",
    },
  ],
};
```

#### `./{section_name}.liquid`

This is the root Liquid file for any section, which get compiled together with the `./schema.ts` based on the env vairables `SHOPIFY_THEME_FOLDER/sections`, by the `shopify-theme-dev` package.&#x20;

The variables and types from the schema will be auto generated on top of the file.

```liquid
{%- comment -%} Auto Generated Variables start {%- endcomment -%}
{%- liquid
  ...
  assign title = section.settings.title
  ...
-%}
{%- comment -%} Auto Generated Variables end {%- endcomment -%}
```

#### `./{section_name}.{block_type}.liquid`

These are files each section block and get copied over into the `SHOPIFY_THEME_FOLDER/snippets` folder.

Any `*.liquid` file also accepts auto translations that are generated for JS and Shopify’s `locales/en.default.json` by placing text content in a special tag.

For example, "Add to Cart" becomes `{{ "product_card.add_to" | t }}` and `window.translations.product_card.add_to = "Add to Cart";` via the `translations.liquid` snippet.


# Getting Started

* [NodeJS](https://nodejs.org/en) v18+
* A package manager -> [npm](https://www.npmjs.com/), [Yarn](https://yarnpkg.com/), or [pnpm](https://pnpm.io/) will work.
* [Shopify CLI](https://shopify.dev/docs/themes/tools/cli/install) v3
* The tech stack specified [here](/smart-theme/for-developers/tech-stack).

## Setting up the codebase

#### Step 1: Clone the repository

Clone the **Accelerate** repository from Github and install it locally by running `pnpm install` (or yarn / npm).

#### Step 2: Create your branch

Create a new branch with a prefix of your name, i.e. `felix/dev/{name_of_feature}`

#### Step 3: Setup your environment variables

Check that the `.env` is configured properly

<pre><code><strong>SHOPIFY_SECTIONS_BEFORE_RENDER=""
</strong>SHOPIFY_SECTIONS_AFTER_RENDER=""
SHOPIFY_THEME_FOLDER=themes/accelerate
SHOPIFY_CMS_LOCALES=
SHOPIFY_CMS_IGNORE_SNIPPETS=color-swatches.json.liquid
SHOPIFY_CMS_IGNORE_LAYOUTS=theme.liquid
SHOPIFY_CMS_IGNORE_SECTIONS=
SHOPIFY_CMS_IGNORE_ASSETS=swatches.json,custom.css.liquid,custom.js
#SHOPIFY_CMS_NO_LOCALIZAZTION=true
#SHOPIFY_CMS_DELETE=true
</code></pre>

The `SHOPIFY_THEME_FOLDER` variable sets your current working directory for all development scripts. It can be set in the `package.json` inline your dev script, or you can change it in the .env file based on what store you are working on.

#### Step 4: Configure your IDE

Ensure that your `.gitignore` and IDE is set to not add any files from the `/themes` directory to the main Git repository.

### **Setting up the Shopify CLI**

#### Step 1: Make a copy of the theme

Always make a copy of the theme that you want to work on, as it's difficult to know who made changes beforehand.

#### Step 2: Configure your scripts

Configure your npm scripts in the `package.json` with the following 2 scripts:

```json
"{store-name}:pull": "shopify theme pull --path themes/{store-name}--store {store-url}.myshopify.com --theme {theme-id}",
"{store-name}:serve": "shopify theme dev --path themes/{store-name}--store {store-url}.myshopify.com --theme {theme-id} --live-reload hot-reload --theme-editor-sync",
```

Example

```json
"bullstrap:pull": "shopify theme pull --path themes/bullstrap --store bullstrap.myshopify.com --theme 132308631746",
"bullstrap:serve": "shopify theme dev --path themes/bullstrap --store bullstrap.myshopify.com --theme 132308631746 --live-reload hot-reload --theme-editor-sync",
```

#### Step 3: Setup your Git repository

Once the configured, *<mark style="color:green;">**and if it is the first time working on the theme,**</mark>*

1. Run the `pull` script to download the theme onto your local machine.&#x20;
2. Use your terminal to `cd themes\\{store_name}`&#x20;
3. Run `git init && git add . && git commit -m "Initial Commit"` to initiate a Git repository **for only the theme files.**&#x20;
4. You also want to setup a GitHub repo using the `platter-base-{store-name}` naming convention and set it as a remote.
5. If you previously worked on the store, make sure that any previous changes on your local machine are committed first, then run the `pull` script to get any changes from the theme. It's important now to check if there are any potential breaking changes. Any changes in the `templates/*.json` files are what the merchants have done within the Theme Editor and will not be affected by any dev tools.
6. Before starting development, it's important to make sure that any changes that were `pulled` in are committed, so that you have a clean slate to start from.&#x20;

#### Step 4: Setup your dev scripts

Make sure that your `dev` script is configured for the correct theme.

**For Windows**

```json
"dev": "set SHOPIFY_THEME_FOLDER=themes/{store_name}&& npm-run-all --parallel dev:tailwindcss dev:esbuild dev:theme dev:assets:js",
```

Alternatively, you can set it directly via the `./.env` file.&#x20;

{% hint style="danger" %}
Adding a space before the ampersands, as follows, will **not** work on Windows. `SHOPIFY_THEME_FOLDER=themes/{store_name} &&`
{% endhint %}

**For Mac**

```json
"dev": "SHOPIFY_THEME_FOLDER=themes/{store_name}&& npm-run-all --parallel dev:tailwindcss dev:esbuild dev:theme dev:assets:js",
```

5. Now you can run `pnpm run dev` in your terminal and in a second terminal `pnpm run shopify:serve` to push your changes up to the Shopify Store. This will also open a new window in your browser to see your changes as you make them.&#x20;

{% hint style="info" %}
If you are working on an old store on an older version, there might be breaking changes that need to be reviewed. This is especially likely if someone else worked on the store previously, so it is important to check the diff after running the dev script for the first time.
{% endhint %}

#### Use of the Accelerated Developer Tools also requires a thorough understanding of the following.

* [Shopify Theme Architecture](https://shopify.dev/docs/themes/architecture) (including all subsections)
* [Shopify Section input types](https://shopify.dev/docs/themes/architecture/settings/input-settings)
* Performance Best Practices
* [Semantic HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Cheatsheet)&#x20;
  * The best example of semantic HTML we've seen is on [stripe.com](https://stripe.com). Review their source code by inspecting the page on Chrome Dev Tools. You will see a strict adherence to \<section> \<header> \<main> \<footer> tags.
* [Accessibility Best Practices](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/CSS_and_JavaScript)

## Getting Started

### First Steps

1. Clone the **Accelerate** repository from Github and install it locally by running `pnpm install` (or yarn / npm).
2. Create a new branch with a prefix of your name, i.e. `felix/dev/{name_of_feature}`
3. Check that the `.env` is configured properly

```
SHOPIFY_SECTIONS_BEFORE_RENDER=""
SHOPIFY_SECTIONS_AFTER_RENDER=""
SHOPIFY_THEME_FOLDER=themes/accelerate
SHOPIFY_CMS_LOCALES=
SHOPIFY_CMS_IGNORE_SNIPPETS=color-swatches.json.liquid
SHOPIFY_CMS_IGNORE_LAYOUTS=theme.liquid
SHOPIFY_CMS_IGNORE_SECTIONS=
SHOPIFY_CMS_IGNORE_ASSETS=swatches.json,custom.css.liquid,custom.js
#SHOPIFY_CMS_NO_LOCALIZAZTION=true
#SHOPIFY_CMS_DELETE=true
```

The `SHOPIFY_THEME_FOLDER` variable sets your current working directory for all development scripts. It can be set in the `package.json` inline your dev script, or you can change it in the .env file based on what store you are working on.

4. Ensure that your `.gitignore` and IDE is set to not add any files from the `/themes` directory to the main Git repository.

### **Working with the Shopify CLI on any store**

1. Same as with the integrated dev tools, unless you are working on your own development store ([platter-dev.myshopify.com](http://platter-dev.myshopify.com)) always make a copy of the Theme that you want to work on, as you never know who made changes beforehand.
2. Configure your npm scripts in the `package.json` with the following 2 scripts:

```json
"{store-name}:pull": "shopify theme pull --path themes/{store-name}--store {store-url}.myshopify.com --theme {theme-id}",
"{store-name}:serve": "shopify theme dev --path themes/{store-name}--store {store-url}.myshopify.com --theme {theme-id} --live-reload hot-reload --theme-editor-sync",
```

Example

```json
"bullstrap:pull": "shopify theme pull --path themes/bullstrap --store bullstrap.myshopify.com --theme 132308631746",
"bullstrap:serve": "shopify theme dev --path themes/bullstrap --store bullstrap.myshopify.com --theme 132308631746 --live-reload hot-reload --theme-editor-sync",
```

3. Once the configured, *<mark style="color:green;">**and if it is the first time working on the theme,**</mark>*
   1. Run the `pull` script to download the theme onto your local machine.&#x20;
   2. Once completed, use your terminal to `cd themes\\{store_name}`&#x20;
   3. Run `git init && git add . && git commit -m "Initial Commit"` to initiate a Git repository **for only the theme files.**&#x20;
   4. You also want to setup a GitHub repo using the `platter-base-{store-name}` naming convention and set it as a remote.
   5. If you previously worked on the store, make sure that any previous changes on your local machine are commited first, then run the `pull` script to get any changes from the theme. Its important now to check if there are any potential breaking changes, Any changes in the `templates/*.json` files are what the merchants have done with the Theme editor and will not be affected by any dev tools.
4. Before starting development, it's important to make sure that any changes that were `pulled` in are committed, so that you have a clean slate to start from. Now you need to make sure that your `dev` script is configured for the correct theme.

**For Windows**

```json
"dev": "set SHOPIFY_THEME_FOLDER=themes/{store_name}&& npm-run-all --parallel dev:tailwindcss dev:esbuild dev:theme dev:assets:js",
```

Alternatively, you can set it directly via the `./.env` file.&#x20;

{% hint style="danger" %}
Adding a space before the ampersands, as follows, will **not** work on Windows. `SHOPIFY_THEME_FOLDER=themes/{store_name} &&`
{% endhint %}

**For Mac**

```json
"dev": "SHOPIFY_THEME_FOLDER=themes/{store_name}&& npm-run-all --parallel dev:tailwindcss dev:esbuild dev:theme dev:assets:js",
```

5. Now you can run `pnpm run dev` in your terminal and in a second terminal `pnpm run shopify:serve` to push your changes up to the Shopify Store. This will also open a new window in your browser to see your changes as you make them.&#x20;

{% hint style="info" %}
If you are working on an old store on an older version, there might be breaking changes that need to be reviewed. This is especially likely if someone else worked on the store previously, so it is important to check the diff after running the dev script for the first time.
{% endhint %}


# Scripts

The following **npm** scripts run from `./assets.package.json`

#### `install`&#x20;

This script runs the `_install-dev-dependencies.js` node script which installs the development dependencies in the `./node_modules` and copies required ignore files.

#### `dev`&#x20;

Runs a parallel watch script for `esbuild` and `tailwindcss` to automatically compile any changes as they are made.

#### `tailwindcss`

&#x20;Runs tailwindcss watch script

#### `esbuild`&#x20;

Runs TypeScript compilation as a watch script

#### `shopify:pull`&#x20;

Pulls any changes made to the configured theme into the local codebase&#x20;

{% hint style="danger" %}
This can override local changes.
{% endhint %}

#### `shopify:serve`&#x20;

Serves local changes onto the configured Shopify Theme, and allows for easy development on [`http://127.0.0.1:9292/`](http://127.0.0.1:9292/)

#### `shopify:create`&#x20;

Creates a new Theme based on the codebase on your configured store.




---

[Next Page](/llms-full.txt/1)

