> For the complete documentation index, see [llms.txt](https://native-app-co.gitbook.io/stork-credit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://native-app-co.gitbook.io/stork-credit/integrations/storefront-and-checkout.md). # Cart & checkout widgets Show customers the store credit their order will earn, before they pay — in the cart and in checkout. Rewards work whether or not customers know about them. But telling them **before** they buy is what turns a reward into an incentive. Stork Credit ships three widgets for that, plus three blocks where shoppers enter a [referral code](/stork-credit/automations/referral-codes.md). The **Cart widget** and **Checkout widget** read your active order-value automations and show what the current cart would earn. The **Threshold widget** is different — it shows checkout-only progress toward a threshold automation's next reward; see [Threshold widget](#threshold-widget) below. {% hint style="warning" %} **The checkout blocks need Shopify Plus.** Shopify only lets apps add blocks to the checkout on stores on the **Shopify Plus** plan. That covers the **Checkout widget**, the **Referral Code block**, and the **Threshold widget**. On any other Shopify plan, they won't appear in **Settings → Checkout → Customize** and can't be shown to shoppers. The **Cart widget** and the **Referral Code theme block** are theme blocks and work on every Shopify plan. So do the **Automatic Store Credit** and **Referral Code** blocks on the **Thank you page**: Shopify allows Thank you page blocks on every plan. To show threshold progress without Shopify Plus, use your theme instead — see [Threshold progress on your storefront](/stork-credit/integrations/threshold-progress-on-your-storefront.md). {% endhint %} ## Cart widget A theme block for your cart page or drawer. Available on every Shopify plan.
The theme editor with the Referral Code block added to the cart, showing the Have a referral code? heading, the code field and the Apply button
### Checking what's live The **Storefront status** card, on the home page and at the top of the **Storefront widgets** page, shows whether each Stork Credit block is live in your **published** theme: * **Stork Credit** — the app embed * **Automatic Store Credit** — the cart block * **Referral Code** — the referral code block Each one is marked **Active** or **Not active**, with a button that opens the theme editor at the right place. On a Shopify Plus store the card also lists the three checkout blocks. The status reflects your published theme only, so a block added to a draft theme shows as **Not active** until that theme is published. After saving in the theme editor, return to the app tab and the status updates. ### Adding it from the app The quickest way is the **Storefront widgets** page in the app navigation. Under **Cart widget** there are two buttons, and each opens the theme editor in a new tab with the change already made: 1. Click **Turn on app embed**. The theme editor opens on **App embeds** with **Stork Credit** switched on. Click **Save**. 2. Click **Add to cart page**. The theme editor opens with the **Automatic Store Credit** block added to your cart page. Drag it where you want it, then click **Save**. 3. Add a product that earns credit to your cart and open the cart page to check the banner appears. Both steps are needed. The app embed is what gives the block the cart contents and the logged-in customer. **In the theme editor the block always shows a sample.** So that you can see, place and style it, the banner appears in the theme editor with a sample amount and a short note underneath, even when the cart is empty. The sample and the note are never shown to shoppers. On your store, the banner appears only when the cart earns credit. {% hint style="warning" %} Without the app embed the block renders nothing. If your banner never appears, check this first. {% endhint %} ### Adding it by hand To do the same thing yourself in the theme editor, or to put the block somewhere other than the cart page: 1. **Online Store → Themes → Customize**. 2. Open your **Cart** page or drawer. 3. **Add block → Apps → Automatic Store Credit**. 4. Open **App embeds** and enable **Stork Credit**. 5. **Save**. ### Styling Three colour settings — background, text, and accent — so the banner can match your theme. Set them in the block's settings in the theme editor. ## Checkout widget A checkout UI extension showing the same information during checkout. **Shopify Plus only.** When a rule that applies to the order [waits for fulfillment or a set time](/stork-credit/automations/order-value-automations.md#when-credit-is-issued), the widget says when the credit arrives, for example *"…in store credit, added to your account once your order ships"* or *"…14 days after your order ships"*. If several rules apply, it gives the latest timing. ### Adding it 1. **Settings → Checkout → Customize**. On a Shopify Plus store you can also click **Open checkout editor** on the **Storefront widgets** page in the app. 2. **Add app block → Automatic Store Credit**. 3. Drag it to where you want it. 4. **Save**. ### On the Thank you page The same block can go on the **Thank you page**, where it shows the credit the order earns, for example *Congratulations, you earned $5.00 in store credit on this order.* It stays hidden when the order earns nothing. Unlike the checkout, the Thank you page works on **every Shopify plan**. 1. **Settings → Checkout → Customize**, and choose **Thank you** from the page menu at the top. 2. **Add app block → Automatic Store Credit**. 3. Drag it to where you want it, and **Save**. The amount is worked out the same way as at checkout, so the same caveats apply. See [Estimates versus what is issued](#estimates-versus-what-is-issued). ### Showing the earned amount in your order confirmation email The Checkout widget's block settings include **Show earned credit in order confirmation email**, off by default. Turn it on and the amount a customer earns is attached to their order, so you can add it to your own order confirmation email template. 1. **Settings → Checkout → Customize → Automatic Store Credit block → Show earned credit in order confirmation email**. Turn it on. 2. **Settings → Notifications → Order confirmation**, and add to the template: ```liquid {{ metafields.stork.credit_earned.value | money }} ``` For an SMS notification template, prefix it: `{{ order.metafields.stork.credit_earned.value | money }}`. {% hint style="warning" %} **Not available for every order.** This is set during checkout, so it only works when the shopper goes through your regular checkout — it isn't set for point-of-sale orders, or orders placed with an accelerated checkout button (Apple Pay, Google Pay, Shop Pay). Those customers still get Shopify's own standard store credit notification confirming what they earned; it just won't appear inside your customized order confirmation email. {% endhint %} {% hint style="info" %} Only order-value automations attach this. Threshold rewards aren't tied to a single order the way an order-value reward is, so they're never included here — see [Threshold progress on your storefront](/stork-credit/integrations/threshold-progress-on-your-storefront.md) for that reward type instead. {% endhint %} ### Referral codes and the checkout widget If you use [referral codes](/stork-credit/automations/referral-codes.md), the checkout widget refreshes as soon as a shopper applies or removes a code in the **Referral Code** block. A shopper whose code makes them eligible for a referral reward rule sees that credit straight away, before they pay. This works for guests too. ## Referral code blocks Three blocks where shoppers enter a [referral code](/stork-credit/automations/referral-codes.md): one for your theme, one for checkout, and one for the Thank you page. All three work for guests and logged-in customers. The theme and checkout blocks behave the same way. An accepted code shows your success message, the code, and a **Remove** link. The code is saved on the order, and you'll see it under the order's **Additional details** as **Referral code**. The Thank you page block works a little differently, because the order already exists. See [Thank you page block](#thank-you-page-block) below. ### Theme block Available on every Shopify plan. The quickest way to add it is from the app: on the **Referral codes** page, under **Add the Referral Code block**, click **Add to theme**. The **Storefront widgets** page has the same button. The theme editor opens with the block already added to your cart page. Move it if you like, then **Save**. To add it to another page, or by hand: 1. **Online Store → Themes → Customize**. 2. Open your **Cart** page, or whichever page you want it on. 3. **Add block → Apps → Referral Code**. 4. **Save**. It doesn't need the Stork Credit app embed. If your theme doesn't offer **Apps** under **Add block**, or you want the code field in a cart drawer, you can paste it into your theme as HTML and Liquid instead. See [Adding it with HTML and Liquid instead](/stork-credit/getting-started/setting-up-referrals.md#adding-it-with-html-and-liquid-instead). In the block's settings you can change: * **Text:** the heading, the field label, the button label, the **Remove** link, and the messages for an applied code, a code already on the customer's account, and an error. The applied message is only used for codes that don't have their own success message. * **Colours:** background, text, button, and button text. A code applied here stays on the shopper's cart. If you also use the checkout block, the shopper sees the code already applied when they reach checkout. ### Checkout block **Shopify Plus only.** On the **Referral codes** page, click **Add to checkout** to open the checkout editor, or go to **Settings → Checkout → Customize**. Then **Add app block → Referral Code**, and **Save**. The **Add to checkout** button only appears on stores on Shopify Plus. ### Thank you page block Available on every Shopify plan. **Settings → Checkout → Customize**, choose **Thank you** from the page menu at the top, then **Add app block → Referral Code**, and **Save**. The shopper sees *Have a referral code?* with a code field and an **Apply** button. When a code is accepted: * The customer is tagged with the code straight away. * If the order is already paid, your referral reward rules run again for it, so the order is still rewarded. * The block shows your success message and the credit the order earned, for example *You've earned $5.00 in store credit on this order*. For an unpaid order it shows what the shopper will earn once it's paid. When a rule is holding the credit until fulfillment or a set time, it reads *You've earned $5.00 in store credit. It will be added to your account a little later.* The block is colour-coded so shoppers can tell at a glance what happened. The colours come from your checkout branding: | Message | Colour | | ---------------------------------------------------------------- | ---------------------------- | | Code accepted, with the credit earned | Green (success) | | A code is already on the customer's account | Blue (information) | | More than 24 hours since the order, so the code can't be applied | Amber (warning) | | Code not valid, or something went wrong | Red (error), under the field | A code can't be removed once applied here. If the shopper already entered a code in the cart or at checkout, the block shows that code instead of the field. The block is translated into English, French, German, Spanish, Italian, Dutch and Brazilian Portuguese. Your success message is always shown as you typed it. See [Referral codes](/stork-credit/automations/referral-codes.md#on-the-thank-you-page) for the full details. ## Threshold widget A separate checkout UI extension that shows progress toward a [threshold automation](/stork-credit/automations/threshold-automations.md)'s next reward — *"you're $80 away from earning $10 in store credit"* — and highlights when completing the current order will cross that line. **Shopify Plus only.** ### Adding it 1. **Settings → Checkout → Customize**. 2. **Add app block → Threshold Store Credit**. 3. Drag it to where you want it. 4. **Save**. ### Styling Checkout UI extensions don't support custom colours — there's no colour-picker field for this surface, unlike the theme blocks above. Instead, the block uses blue while the customer is progressing and switches to green once this order will push them over their next threshold, and follows whatever colours your [checkout branding](https://help.shopify.com/en/manual/checkout-settings/checkout-branding) already assigns to those states. The only setting is **Show progress bar** — on by default, showing a filled bar alongside the message. Turn it off to show the text alone. ### When it stays hidden Same idea as the widgets above, plus its own conditions: * The shopper isn't logged in — threshold progress is tracked per customer, so a guest checkout shows nothing. * No threshold automation is active for the shop. * The customer has already passed the rule's optional spend cap — there's no next reward to show progress toward. ## Threshold rewards and the widgets **The order-value widgets above show order-value rewards only** — a threshold automation never appears in the **Cart widget** or **Checkout widget**, even while it's active and the shopper is on track to earn from it. Threshold progress has its own dedicated **Threshold widget** (above) instead. That split exists because a threshold reward isn't earned by a single cart the way an order-value reward is. It's earned when a customer's **lifetime spend** crosses a line — normally settled by the automation's own scheduled run, not at the instant of payment. The Threshold widget shows a **live estimate** of that same crossing (current lifetime spend, plus this order, against the customer's stored next-threshold marker), with the same estimate-versus-issued gap described below — see the next section for what can make the two disagree. {% hint style="warning" %} Don't read the order-value widgets' silence as "no threshold reward". A shopper can see nothing in either of those and still earn threshold credit from the order once the automation next runs. Add the Threshold widget if you want that progress visible at checkout. {% endhint %} To show the same progress outside of checkout, use your theme instead — see [Threshold progress on your storefront](/stork-credit/integrations/threshold-progress-on-your-storefront.md). ## When the widgets stay hidden Both hide themselves rather than showing a zero. Nothing appears when: * No active automation matches the current cart. * The matching rule's minimum requirement isn't met yet. * The rule targets a segment or customer list and the shopper isn't in it. * The shopper isn't logged in and the rule targets specific customers. The widget updates as the cart changes, so adding an item that crosses a minimum threshold makes it appear. ## Estimates versus what is issued The widgets show an **estimate from the cart**. The credit that is actually issued is calculated from the **paid order**. They can differ, legitimately: * A discount code applied at checkout changes the order value the reward is based on — unless the rule uses the pre-discount [calculation base](/stork-credit/automations/order-value-automations.md), in which case the code makes no difference. * Shipping and taxes are never part of the calculation, in either place. * Changing the cart after seeing the banner changes the reward. * A rule can be deactivated between the cart view and the order being paid. * A rule that [waits before issuing](/stork-credit/automations/order-value-automations.md#when-credit-is-issued) issues nothing for a cancelled order, and less if items are refunded during the wait. The amount in your order confirmation email is the estimate made at checkout and isn't updated. The **Cart widget** shows the text you set on the block. If your rules wait for fulfillment or a set time, check that the text doesn't promise the credit straight away. {% hint style="info" %} The order-value automation is always the source of truth. The widgets are a shop-front for it, not a second calculation you can rely on. {% endhint %} **The Threshold widget carries its own version of the same gap.** It projects the customer's lifetime spend *plus this order* against their stored next-threshold marker, at the moment checkout loads. Between then and the automation actually crediting the order: * A refund or cancellation before the automation's next run changes the lifetime spend the crossing is judged against. * A rule with a [hold before issuing](/stork-credit/automations/threshold-automations.md#holding-credit-before-it-is-issued) doesn't issue immediately even after a genuine crossing — the widget's "unlocked" message describes the crossing, not the timing of the payout. * The rule can be edited or deactivated between checkout and the next scheduled run. The customer's [next-threshold metafield](/stork-credit/integrations/threshold-progress-on-your-storefront.md) and [run history](/stork-credit/automations/run-history.md) are the source of truth for what was actually issued — the widget is a live estimate, same as the order-value ones above. ## Guest shoppers Store credit is held on a customer record. When a guest checks out, Shopify matches the order to a customer by email, or creates a new customer, and that customer receives the credit. The guest needs to sign in with the same email to see and spend it. Shopify's store credit notification email tells them the credit is there. Before the order is placed, the widgets can't tell which customer a guest will become. So rules limited to segments or specific customers stay hidden for guests. Rules for **all customers** still show, and so do tag rules matched by a [referral code](/stork-credit/automations/referral-codes.md) the guest has entered. ## Multiple rules When several rules match the same cart, the widget reflects your [promotion stacking](/stork-credit/automations/promotion-stacking.md) setting — the combined total when stacking is on, the single best reward when it's off.