` deep link opens the panel straight to that section. 5. Customers can apply earned rewards, redeem points, set their birthday and share their referral link from inside the panel. ### Custom login trigger By default, a logged-out customer who taps a sign-in link in the panel goes to the Shopify account login page. If your store uses its own login (a popup or a third-party login app), set a **Custom login trigger** in [Loyalty → Settings](/loyalty/program-settings): * **Use a CSS element:** Yuko clicks an existing element on the page, such as your theme's login button. Enter its **Login element selector**, for example `#login-button` or `a[href='/account']`. * **Use a link:** Yuko sends the customer to the **Login link** you enter. The same setting applies to Loyalty Nudges and the Cart redeem widget. ### Limitations * The button sits in a bottom corner. Mid-page positions aren't supported. * It doesn't render in Shopify Checkout. * The **Yuko App** embed must be on. See [Theme App Embed](/installation-and-setup/theme-app-embed). ## Examples * **Menu link to rewards:** add a "Rewards" item to your main menu that links to `#yuko-ways-to-redeem`, so the panel opens on what customers can spend their points on. * **Booster spotlight:** turn on **Featured booster** during a double-points weekend so every panel opens with that offer at the top of the home page. * **Clear of your chat app:** place Floating Rewards on the left and keep your support chat on the right, or raise **Bottom spacing** so the two don't overlap. ## Best practices **Stay clear of chat widgets.** Use the opposite corner, or raise **Bottom spacing**, so Floating Rewards doesn't sit on top of your support chat. **Add a deep link to your navigation.** A menu item that opens the panel is easier to find than the floating button alone. **Use Icon only on mobile.** On small screens a compact button covers less of your product content. **Write both audiences.** Visitors and members see different home pages, so check both in the preview. ## FAQs Yes. In **Customization → Visibility**, tick **Hide on homepage** or add URL conditions under **Hide Floating Rewards in URLs that contain**. To hide it on one device type, set **Where to display the Floating Rewards** to **Desktop** or **Mobile**. Yes. Copy the link from **Customization → Deep link** (for example `#yuko-vip`) and use it as the link on any menu item or button. Floating Rewards renders inside a shadow DOM to keep its styles separate from your theme. Add styling in **Customization → Custom CSS** instead. Set a **Custom login trigger** in [Loyalty → Settings](/loyalty/program-settings) so Yuko starts your store's own login flow. Use the **Editing language** picker at the top of the editor. Each of your store's published languages keeps its own copy of the text. Campaign and reward names are translated in [Translations](/account/translations). No. Use [Checkout Earn](/onsite-widgets/checkout-earn) and [Checkout Redeem](/onsite-widgets/checkout-redeem) in Shopify Checkout. ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Loyalty Nudges Source: https://docs.yuko.so/onsite-widgets/loyalty-nudges A strip pinned to the top or bottom of every storefront page that opens a loyalty drawer with the customer's points, VIP tier, rewards, ways to earn (including booster campaigns) and ways to redeem. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets → Loyalty Nudges ## Introduction Loyalty Nudges is a slim strip pinned to the top or bottom of every storefront page. When a customer taps it, a drawer slides open with their points balance, VIP tier, earned rewards, ways to earn (including active **booster campaigns**) and ways to redeem, without leaving the page. It's a natural home for [Booster Campaigns](/loyalty/booster-campaigns/overview): once a booster is live, shoppers see it on every page without you sending an email. ## What problem this solves A loyalty program that only lives in the customer account is invisible to someone browsing products. Loyalty Nudges keeps the program in view on every page with one short line of text, and opens the full detail only when the customer asks for it. ## Where it appears * A **strip** pinned to the **Bottom of page** (default) or **Top of page**. * A **drawer** that opens when the customer taps the strip. * Every storefront page, rendered through the **Yuko App** theme app embed. There's no block to place. ## When to use * You run booster campaigns and want them visible on every page. * You want a persistent loyalty surface that carries a short personalised message. * You want points, rewards, VIP and boosters together in one place on the storefront. ## Overview * A strip with separate **Logged-out text** and **Logged-in text**. * A drawer with four sections (**Header banner**, **Your rewards**, **Ways to earn** and **Ways to redeem**) that you can reorder by dragging and switch on or off. * The header banner has a **Member** version (points and tier) and a **Visitor** version (a "join our loyalty program" card). The rest of the drawer is the same for both, but visitors don't get action buttons until they join. * Booster campaigns can show all active boosters or a hand-picked list. * **Visibility** controls for top or bottom placement, device and URL exclusions. * Colours, **Drawer Height** and **Custom CSS** on the **Styles** tab. * Each language has its own copy of the text. Use the **Editing language** picker. ## Before you start Yuko is installed on your Shopify store. The program this widget belongs to is set up and enabled. The widget is switched on with the toggle on its card in Yuko's **Widgets** page (for loyalty widgets, **Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets**). For storefront widgets, your active theme is an Online Store 2.0 theme that supports app embeds and app blocks. The **Yuko App** embed is turned on in your published theme. See [Theme App Embed](/installation-and-setup/theme-app-embed). ## Setup guide ### 1. Configure in Yuko All content settings are on the **Configuration** tab. Go to **Apps → Yuko Loyalty → Loyalty → Widgets** and click **Customize** on **Loyalty Nudges**. In **Widget content → Trigger Strip**: * **Logged-out text**, shown to visitors. Default: *Earn `[points_label]` & rewards every time you shop*. Keep it inviting: visitors can still open the drawer and browse. * **Logged-in text**, shown to members. Supports `[first_name]`, `[customer_name]`, `[point_balance]` and `[points_label]`, for example *Hey `[first_name]`, you have `[point_balance]` `[points_label]`!* In **Widget content → Drawer Content**: * **Drawer title**, shown in the drawer's header bar. Default: *MY LOYALTY PROGRAM*. * **Greeting**, shown at the top of the drawer. Supports `[first_name]` and `[customer_name]`. In **Drawer sections**, drag **Header banner**, **Your rewards**, **Ways to earn** and **Ways to redeem** into order, tick the ones to show, and expand each one to edit its text (see the table below). In **Booster campaigns**, keep **Show booster campaigns** on to show boosters inside Ways to earn. Under **Campaigns to show**, leave everything unselected to show every active booster, or select specific campaigns. The **Ways to earn** section must be on for boosters to appear. In **Visibility**: * **Placement:** **Bottom of page** (default) or **Top of page**. * **Where to display the loyalty strip:** **Desktop and mobile** (default), **Desktop** or **Mobile**. * **Hide loyalty strip in URLs that contain:** click **Add new condition** and enter text such as `/blog`. The strip is hidden on every URL that contains it. On the **Styles** tab, set **Primary color**, **Secondary color**, **Text color** and **Body description color**, the **Drawer Height** (30–100 vh; leave empty for the default) and any **Custom CSS**. Click **Save** and switch the widget on. #### Drawer section settings | Section | Settings | | - | - | | **Header banner** (Member) | **Points section heading** (default *Your Balance*), **Points balance text** (`[point_balance] [points_label]`), **Points worth text** (*Worth `[points_cash_value]`*), **Points multiplier benefit text** (`[multiplier_value]x multiplier`, shown only when the multiplier is greater than 1), and the **Points balance**, **Points worth value** and **VIP tier** toggles. | | **Header banner** (Visitor) | **Title** (default *Join Our Loyalty Program*), **Description**, **Create account button** (default *Join Now*) and **Sign in**. In **Sign in**, `[signin:Sign in]` becomes a sign-in link and the text inside becomes the link text. | | **Your rewards** | **Your Rewards heading**, **Apply button text (Your Rewards)** and **Expiration label (Your Rewards)** (*Expires on `[expiration_date]`*, hidden automatically when a reward doesn't expire). | | **Ways to earn** | **Ways to earn heading**, **Ways to earn — order** (**Booster campaigns first**, the default, or **Standard campaigns first**), **Edit date button text**, **Save date button text** and **Cancel button text** for birthday campaigns, and **Like**, **Follow**, **Share** and **Visit** button text for social and visit campaigns. | | **Ways to redeem** | **Ways to redeem heading**, **Redeem button text (Ways to Redeem)**, **Insufficient points text** (*Needs `[points_needed]` more `[points_label]`*) and **Load more button**. | At least one of **Points balance**, **VIP tier** or **Your rewards** must stay on. ### 2. Add to your storefront Loyalty Nudges renders on every page through the **Yuko App** embed, so there's no block to add. If the embed is on and the widget is active, the strip appears on your storefront. ### 3. Verify Open your store in a private window. The strip shows your logged-out text, and the drawer opens with the visitor header card. Log in as a customer. The strip switches to your logged-in text, and the drawer shows their balance, tier and rewards. With at least one active booster campaign, open the drawer and check that it appears under Ways to earn. Open a URL that matches one of your conditions and confirm the strip is hidden. ## Available placeholders | Placeholder | Replaced with | | - | - | | `[first_name]` | The customer's first name (logged-in only). | | `[customer_name]` | The customer's full name (logged-in only). | | `[point_balance]` | The customer's current points balance. | | `[points_label]` | Your points label from Loyalty → Settings. | | `[points_cash_value]` | What the balance is worth in your store currency. | | `[multiplier_value]` | The customer's VIP tier multiplier. | | `[expiration_date]` | A reward's expiry date. | | `[points_needed]` | How many more points a reward needs. | See [all widget placeholders](/onsite-widgets/overview#placeholders). ## How it works 1. The **Yuko App** embed loads Loyalty Nudges on every page, unless the device or URL is excluded. 2. Visitors see the logged-out strip. Members see the logged-in strip, personalised with their name and balance. 3. Tapping the strip opens the drawer with the sections you enabled, in your order. 4. Booster campaigns load live, filtered by your **Campaigns to show** selection, and show progress where the campaign type supports it. 5. Members can apply rewards and redeem points straight from the drawer. Visitors can browse, then create an account or sign in. ### Custom login trigger By default, the visitor **Create account button** and sign-in link go to the Shopify account login page. If your store uses its own login (a popup or a third-party login app), set a **Custom login trigger** in [Loyalty → Settings](/loyalty/program-settings). Choose **Use a CSS element** and enter a **Login element selector** (such as your theme's login button), or **Use a link** and enter a **Login link**. The same setting applies to Floating Rewards and Cart redeem. ### Decision guidance * **Top or bottom:** bottom is easier to reach on mobile and stays out of the way of sticky headers. Top is more prominent. * **All boosters or a hand-picked list:** start with all. Narrow the list if you run many campaigns at once. * **Boosters first or standard campaigns first:** boosters first puts time-limited offers at the top. ### Limitations * Loyalty Nudges doesn't render in Shopify Checkout. Use [Checkout Earn](/onsite-widgets/checkout-earn) and [Checkout Redeem](/onsite-widgets/checkout-redeem) there. * It reaches only customers who are on your store. Use [emails](/emails/overview) for everyone else. ## Examples * **Double-points weekend:** the drawer opens with your Multiplier booster at the top of Ways to earn on every page. * **Spending-goal progress:** a Spending Goal booster shows each member how close they are to the bonus. * **Personal strip:** *Hey Sarah, you have 240 points!* on every page reminds members of their balance. ## Best practices **Turn on Loyalty Nudges before you launch a booster.** It's the simplest way to show the campaign on every page. **Personalise the logged-in text.** Use `[first_name]` and `[point_balance]` so the strip reads as personal. **Exclude pages where the strip competes.** Blog posts and dedicated landing pages are common choices. **Test on mobile first.** Most shoppers will open the drawer on a phone, so check the **Drawer Height** there. ## FAQs [Floating Rewards](/onsite-widgets/floating-launcher) is a corner button that opens a full panel with VIP, referrals, membership and activity. Loyalty Nudges is a full-width strip with a message, which opens a drawer focused on points, rewards, earning and redeeming. You can use either or both. Check that the booster is active, **Show booster campaigns** is on, the **Ways to earn** section is on, and the booster is selected under **Campaigns to show** (or nothing is selected, so all show). The customer must also match the campaign's targeting. Yes. Use the **Editing language** picker at the top of the editor. Each of your store's published languages keeps its own copy of the text. Yes. Add URL conditions under **Visibility → Hide loyalty strip in URLs that contain**. To show it on only one device type, choose **Desktop** or **Mobile**. Set **Drawer Height** on the **Styles** tab, between 30 and 100 (percent of the screen height). Leave it empty to use the default. ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Order List Balance Widget Source: https://docs.yuko.so/onsite-widgets/order-list-balance Show the customer's points balance on the Orders page in Shopify customer accounts. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets → Order List: Point Balance ## Introduction The **Order List: Point Balance** widget shows the customer's points balance at the top of the Orders page in their customer account. It's the **Yuko Order index points display** customer account UI extension block, not a theme app block. ## What problem this solves Customers check their orders often. Showing their balance there reminds them they have points to spend on the next order. ## Where it appears * The Orders page in Shopify customer accounts (`customer-account.order-index.block.render`), at the top of the page by default. ## When to use * You use Shopify's customer accounts. * You want a lightweight balance reminder without a full loyalty page. ## Overview * Two text fields: a title and a description. * No Styles tab; the block uses Shopify customer accounts styling. * Shows only for customers with a points balance. ## Before you start Yuko is installed on your Shopify store. The program this widget belongs to is set up and enabled. The widget is switched on with the toggle on its card in Yuko's **Widgets** page (for loyalty widgets, **Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets**). For storefront widgets, your active theme is an Online Store 2.0 theme that supports app embeds and app blocks. Your store uses Shopify customer accounts (**Settings → Customer accounts**). ## Setup guide ### 1. Configure the widget in Yuko Go to **Loyalty → Widgets**, find **Order List: Point Balance** under **Post-Purchase**, and click **Customize**. * **Title**: default `You have [point_balance] [points_label]` * **Description**: default `Redeem your [points_label] for rewards & discounts on your next order` Click **Save**. Back on **Loyalty → Widgets**, switch the widget's toggle on. ### 2. Add the block in the customer accounts editor In your Shopify admin, go to **Settings → Customer accounts** and click **Customize**. Use the page selector at the top to open the page where the block should appear (Order status, Orders, or Profile). Click **Add app block** and choose the Yuko block for this widget (for example **Yuko Order status earned points**, **Yuko Order index points display** or **Yuko Profile loyalty program**). Position the block where customers will see it and click **Save**. Customer account blocks only work with Shopify's **new customer accounts**. Check that they're turned on in **Settings → Customer accounts**. On the **Orders** page, add the **Yuko Order index points display** block. See [Customer Account Extension](/installation-and-setup/customer-account-extension) for more detail. ### 3. Verify Log in as a customer with points and open the Orders page in their account. ## Available placeholders | Placeholder | Replaced with | | - | - | | `[point_balance]` | Customer's points balance. | | `[points_label]` | Your loyalty points label. | | `[points_cash_value]` | Cash value of the customer's points. | ## How it works 1. A logged-in customer opens the Orders page. 2. The block fetches their balance from Yuko. 3. If they have a balance, the block shows your title and description. Customers with no points don't see it. ### Limitations * Works only with Shopify customer accounts; it isn't a theme block. * The block's look follows Shopify's customer accounts styling. ## FAQs The block is hidden when the customer's balance is zero. Also check that the widget toggle is on and the block is added to the **Orders** page. Use the [Loyalty Rewards: Customer Account Page](/onsite-widgets/customer-account-page) widget. ## Full placeholder reference Placeholders are written in square brackets, for example `[points_label]`. Each text field's help text in the widget editor lists the placeholders that field supports. **Available in every storefront widget text** | Placeholder | Replaced with | | - | - | | `[points_label]` | Your points label from **Loyalty → Settings** (singular or plural, e.g. *point* / *points*). | | `[point_balance]` | The customer's current points balance. | | `[points_cash_value]` | What the customer's balance is worth in your store currency, based on your points-to-cash conversion rate. | | `[store_name]` | Your store name. | **Widget-specific placeholders** | Placeholder | Replaced with | Used in | | - | - | - | | `[points_value]` | Points the customer can earn on this product, cart or order. | Product page, Cart earn, Checkout earn, Order status earn | | `[first_name]` | The customer's first name (logged-in customers only). | Cart redeem greeting, Loyalty Nudges | | `[customer_name]` | The customer's full name (logged-in customers only). | Loyalty Nudges | | `[points_needed]` | How many more points the customer needs for a reward. | Insufficient-points text (Cart redeem, Loyalty Nudges) | | `[expiration_date]` | The expiry date of an earned reward. Hidden automatically when the reward doesn't expire. `[discount_expiry_date]` works the same way. | Reward expiry text (Cart redeem, Loyalty Nudges, Floating Rewards) | | `[points_to_redeem]` | The number of points the customer chose to redeem. | Checkout redeem summary | | `[discount_value]` | The discount those points unlock. | Checkout redeem summary | | `[tier_name]` | A VIP tier name. | VIP tier text (Floating Rewards) | | `[next_tier]` | The name of the customer's next VIP tier. | VIP progress text | | `[tier_entry_amount]` | The threshold needed to enter a tier. | Cart redeem tier entry text | | `[tier_reach_level]` | The threshold needed to reach a tier. | Floating Rewards VIP text | | `[multiplier_value]` | The points multiplier for a VIP tier (e.g. *2*). Shown only when the multiplier is greater than 1. | Points multiplier benefit text | | `[renewal_date]` | The date a paid membership renews. | Floating Rewards membership text | ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Order Status Earn Widget Source: https://docs.yuko.so/onsite-widgets/order-status-earn Confirm the points a customer earned for an order on the order status page in Shopify customer accounts. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets → Order Status: Earn Points Message ## Introduction The **Order Status: Earn Points Message** widget tells customers how many points an order earned them, on that order's status page. It's the **Yuko Order status earned points** customer account UI extension block, not a theme app block. ## What problem this solves Right after buying, customers are most engaged. Confirming the points they earned shows the program is working and plants the idea of the next purchase. ## Where it appears * The order status page in Shopify customer accounts (`customer-account.order-status.block.render`). By default it sits in the order summary; you can move it in the customer accounts editor. ## When to use * You use Shopify's customer accounts. * You want a simple confirmation of earned points after every order. ## Overview * Two text fields: a title and a message. * No Styles tab; the block uses Shopify customer accounts styling. * Shows only for orders that earned points. ## Before you start Yuko is installed on your Shopify store. The program this widget belongs to is set up and enabled. The widget is switched on with the toggle on its card in Yuko's **Widgets** page (for loyalty widgets, **Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets**). For storefront widgets, your active theme is an Online Store 2.0 theme that supports app embeds and app blocks. Your store uses Shopify customer accounts (**Settings → Customer accounts**). ## Setup guide ### 1. Configure the widget in Yuko Go to **Loyalty → Widgets**, find **Order Status: Earn Points Message** under **Post-Purchase**, and click **Customize**. * **Order status earn title**: default `You have earned` * **Order status earn message**: default `[points_value] [points_label] for this order.` Click **Save**. Back on **Loyalty → Widgets**, switch the widget's toggle on. ### 2. Add the block in the customer accounts editor In your Shopify admin, go to **Settings → Customer accounts** and click **Customize**. Use the page selector at the top to open the page where the block should appear (Order status, Orders, or Profile). Click **Add app block** and choose the Yuko block for this widget (for example **Yuko Order status earned points**, **Yuko Order index points display** or **Yuko Profile loyalty program**). Position the block where customers will see it and click **Save**. Customer account blocks only work with Shopify's **new customer accounts**. Check that they're turned on in **Settings → Customer accounts**. On the **Order status** page, add the **Yuko Order status earned points** block. See [Customer Account Extension](/installation-and-setup/customer-account-extension) for more detail. ### 3. Verify Place a test order as a logged-in customer, then open that order in the customer account. Check that the block shows the points earned. ## Available placeholders | Placeholder | Replaced with | | - | - | | `[points_value]` | The points earned on this order. | | `[points_label]` | Your loyalty points label. | | `[points_cash_value]` | Cash value of the points earned. | ## How it works 1. A customer opens an order in their customer account. 2. The block reads the points recorded for that order. 3. If the order earned points, the block shows your title and message. Otherwise it stays hidden. ### Limitations * Works only with Shopify customer accounts; it isn't a theme block. * The block's look follows Shopify's customer accounts styling. ## FAQs The block is hidden when the order didn't earn points, for example if no earn rule applied or the customer is excluded from the program. Also check that the widget toggle is on and the block is added to the **Order status** page. No. [Checkout: Earn points](/onsite-widgets/checkout-earn) shows the points a customer *will* earn during checkout. This widget confirms the points recorded for a placed order. ## Full placeholder reference Placeholders are written in square brackets, for example `[points_label]`. Each text field's help text in the widget editor lists the placeholders that field supports. **Available in every storefront widget text** | Placeholder | Replaced with | | - | - | | `[points_label]` | Your points label from **Loyalty → Settings** (singular or plural, e.g. *point* / *points*). | | `[point_balance]` | The customer's current points balance. | | `[points_cash_value]` | What the customer's balance is worth in your store currency, based on your points-to-cash conversion rate. | | `[store_name]` | Your store name. | **Widget-specific placeholders** | Placeholder | Replaced with | Used in | | - | - | - | | `[points_value]` | Points the customer can earn on this product, cart or order. | Product page, Cart earn, Checkout earn, Order status earn | | `[first_name]` | The customer's first name (logged-in customers only). | Cart redeem greeting, Loyalty Nudges | | `[customer_name]` | The customer's full name (logged-in customers only). | Loyalty Nudges | | `[points_needed]` | How many more points the customer needs for a reward. | Insufficient-points text (Cart redeem, Loyalty Nudges) | | `[expiration_date]` | The expiry date of an earned reward. Hidden automatically when the reward doesn't expire. `[discount_expiry_date]` works the same way. | Reward expiry text (Cart redeem, Loyalty Nudges, Floating Rewards) | | `[points_to_redeem]` | The number of points the customer chose to redeem. | Checkout redeem summary | | `[discount_value]` | The discount those points unlock. | Checkout redeem summary | | `[tier_name]` | A VIP tier name. | VIP tier text (Floating Rewards) | | `[next_tier]` | The name of the customer's next VIP tier. | VIP progress text | | `[tier_entry_amount]` | The threshold needed to enter a tier. | Cart redeem tier entry text | | `[tier_reach_level]` | The threshold needed to reach a tier. | Floating Rewards VIP text | | `[multiplier_value]` | The points multiplier for a VIP tier (e.g. *2*). Shown only when the multiplier is greater than 1. | Points multiplier benefit text | | `[renewal_date]` | The date a paid membership renews. | Floating Rewards membership text | ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Onsite Widgets Source: https://docs.yuko.so/onsite-widgets/overview Show points, rewards and VIP status across your storefront, cart, checkout and customer accounts, plus a floating rewards panel and a dedicated loyalty page. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets ## What are onsite widgets Onsite widgets are the customer-facing parts of your loyalty program. They show points balances, what customers can earn, rewards to redeem and VIP status at each step of the shopping journey, with no theme code to write. Each widget has a toggle to switch it on and a **Customize** button to edit its text, colours and settings. **Customize Branding** at the top of the page sets colours for all widgets at once. See [Branding & Locale](/onsite-widgets/branding-and-locale). Widgets render through three kinds of Shopify extension: * **Theme app extension**: the **Yuko App** app embed (Floating Rewards, Loyalty Nudges and automatic cart placement) and the Yuko theme blocks you add in the theme editor (product, cart and landing page blocks). * **Checkout UI extension**: blocks inside Shopify Checkout. * **Customer account UI extension**: blocks on the Order status, Orders and Profile pages, plus a full loyalty page, in Shopify's new customer accounts. ## The Widgets list Widgets are grouped as they appear in the admin. ### Landing & Promotional | Widget | Where it appears | How it renders | | - | - | - | | [Floating Rewards](/onsite-widgets/floating-launcher) (Recommended) | A floating button and panel on every page | Yuko App embed | | [Rewards Landing Page](/onsite-widgets/rewards-landing-page) (Recommended) | A loyalty page at `/pages/loyalty-info-page` | Seven Yuko theme blocks | | [Loyalty Nudges](/onsite-widgets/loyalty-nudges) | A strip pinned to the top or bottom of every page | Yuko App embed | ### Shopping Cart | Widget | Where it appears | How it renders | | - | - | - | | [Product page](/onsite-widgets/product-page-earn) | Product detail page | Theme block **Yuko:Product Earn Message** | | [Cart earn message](/onsite-widgets/cart-earn) | Cart page or drawer | Automatic placement through the Yuko App embed, or theme block **Yuko: Cart Earn Message** | | [Cart redeem message](/onsite-widgets/cart-redeem) | Cart page or drawer | Automatic placement through the Yuko App embed, or theme block **Yuko: Cart Redeem Message** | ### Checkout Process | Widget | Where it appears | How it renders | | - | - | - | | [Checkout: Earn points](/onsite-widgets/checkout-earn) | Shopify Checkout | Checkout UI extension block **Yuko Potential points earn** | | [Checkout: Redeem points](/onsite-widgets/checkout-redeem) | Shopify Checkout | Checkout UI extension block **Yuko Redeem rewards** | Checkout widgets are **available only on the Shopify Plus plan**, because Shopify allows checkout UI extension blocks only on Plus stores. They're also available on select Yuko plans. ### Post-Purchase | Widget | Where it appears | How it renders | | - | - | - | | [Order Status: Earn Points Message](/onsite-widgets/order-status-earn) | Order status page in customer accounts | Customer account UI extension block **Yuko Order status earned points** | | [Order List: Point Balance](/onsite-widgets/order-list-balance) | Orders page in customer accounts | Customer account UI extension block **Yuko Order index points display** | | [Customer Profile: Point Balance](/onsite-widgets/customer-profile-balance) | Profile page in customer accounts | Customer account UI extension block **Yuko Profile loyalty program** | | [Loyalty Rewards: Customer Account Page](/onsite-widgets/customer-account-page) | A full loyalty page in customer accounts | Customer account UI extension page **Yuko Loyalty account page** (available on select plans) | ## All widgets Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. ## Placeholders Most widget text fields accept placeholders that Yuko replaces with live values: Placeholders are written in square brackets, for example `[points_label]`. Each text field's help text in the widget editor lists the placeholders that field supports. **Available in every storefront widget text** | Placeholder | Replaced with | | - | - | | `[points_label]` | Your points label from **Loyalty → Settings** (singular or plural, e.g. *point* / *points*). | | `[point_balance]` | The customer's current points balance. | | `[points_cash_value]` | What the customer's balance is worth in your store currency, based on your points-to-cash conversion rate. | | `[store_name]` | Your store name. | **Widget-specific placeholders** | Placeholder | Replaced with | Used in | | - | - | - | | `[points_value]` | Points the customer can earn on this product, cart or order. | Product page, Cart earn, Checkout earn, Order status earn | | `[first_name]` | The customer's first name (logged-in customers only). | Cart redeem greeting, Loyalty Nudges | | `[customer_name]` | The customer's full name (logged-in customers only). | Loyalty Nudges | | `[points_needed]` | How many more points the customer needs for a reward. | Insufficient-points text (Cart redeem, Loyalty Nudges) | | `[expiration_date]` | The expiry date of an earned reward. Hidden automatically when the reward doesn't expire. `[discount_expiry_date]` works the same way. | Reward expiry text (Cart redeem, Loyalty Nudges, Floating Rewards) | | `[points_to_redeem]` | The number of points the customer chose to redeem. | Checkout redeem summary | | `[discount_value]` | The discount those points unlock. | Checkout redeem summary | | `[tier_name]` | A VIP tier name. | VIP tier text (Floating Rewards) | | `[next_tier]` | The name of the customer's next VIP tier. | VIP progress text | | `[tier_entry_amount]` | The threshold needed to enter a tier. | Cart redeem tier entry text | | `[tier_reach_level]` | The threshold needed to reach a tier. | Floating Rewards VIP text | | `[multiplier_value]` | The points multiplier for a VIP tier (e.g. *2*). Shown only when the multiplier is greater than 1. | Points multiplier benefit text | | `[renewal_date]` | The date a paid membership renews. | Floating Rewards membership text | ## Languages and logged-out customers * **Languages:** every widget editor has an **Editing language** picker when your store publishes more than one language. Each language keeps its own copy of the widget text. See [Branding & Locale](/onsite-widgets/branding-and-locale). * **Custom login trigger:** when a logged-out customer signs in from Floating Rewards, Loyalty Nudges or Cart redeem, Yuko sends them to the Shopify account login by default. If your store uses its own login, set a **Custom login trigger** (a CSS element to click, or a login link) in [Loyalty → Settings](/loyalty/program-settings). ## Decision guidance * **Start with the recommended pair:** Floating Rewards keeps the program one tap away on every page, and the Rewards Landing Page gives your emails, ads and footer a destination. * **Add cart widgets** so customers see what they'll earn and can redeem before checkout. * **Add checkout widgets** if you're on Shopify Plus. * **Add the customer account widgets** so balances and rewards show up where customers check their orders. * **Add Loyalty Nudges** when you run booster campaigns and want them visible on every page. ## Best practices **Less is more.** Pick the surfaces that matter for your store rather than switching everything on. **Keep widget copy short.** Link to the Rewards Landing Page for the full explanation. **Always test on mobile.** Most loyalty interactions happen on phones. ## Related The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Product Page Earn Widget Source: https://docs.yuko.so/onsite-widgets/product-page-earn Show customers how many points they will earn on a product, directly on the product detail page. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets → Product page ## Introduction The **Product page** widget shows the points a customer will earn by buying the product they're looking at, right on the product detail page. ## What problem this solves Customers who don't realise they're earning won't change their behaviour because of the program. Showing the earn value on the product page, while the customer is deciding, makes the program visible at the right moment. ## Where it appears * Product detail pages, wherever you place the **Yuko:Product Earn Message** theme app block. ## When to use * You want loyalty visible while customers consider a purchase. * Your order values are high enough that the per-product earn is meaningful. ## Overview * One message field with placeholders. * Default or custom icon. * Styles tab with colours, padding, width, height and **Custom CSS**. * Updates when the customer switches variants. * Edit the text per language with the **Editing language** picker. ## Before you start Yuko is installed on your Shopify store. The program this widget belongs to is set up and enabled. The widget is switched on with the toggle on its card in Yuko's **Widgets** page (for loyalty widgets, **Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets**). For storefront widgets, your active theme is an Online Store 2.0 theme that supports app embeds and app blocks. ## Setup guide ### 1. Configure the widget in Yuko Go to **Loyalty → Widgets**, find **Product page** under **Shopping Cart**, and click **Customize**. **Points earned on product page**. Default: `You'll earn [points_value] [points_label] on this purchase!` Under **Customize product message icon**, keep **Default** or choose **Custom** to upload your own icon (JPG, PNG, GIF or WEBP, under 1 MB). On the **Styles** tab, set: * **Color Configuration:** Border color, Background color, Text color and Button background color. * **Widget Style:** Padding (px, default 10), Width (%, default 100) and Height (px, leave empty for automatic). * **Custom CSS:** add your own CSS rules for this widget. Click **Save**. Back on **Loyalty → Widgets**, switch the widget's toggle on. ### 2. Add the block to your product template The widget editor shows an **Add Block** button that opens the theme editor on your product template with the block ready to add. You can also add it manually: Theme blocks get their content from Yuko's storefront script, which loads through the **Yuko App** app embed. If you haven't already, enable it in **Online Store → Themes → Customize → App embeds**. See [Theme App Embed](/installation-and-setup/theme-app-embed). In your Shopify admin, go to **Online Store → Themes**, find your active theme, and click **Customize**. Use the template selector at the top to open the page where this widget should appear (Product, Cart, a page template, and so on). Click **Add block** in the section where you want the widget. Under **Apps**, select the Yuko block named for this widget (block names start with **Yuko:**). Drag the block to your preferred position and click **Save**. Pick a **Product** template and add the **Yuko:Product Earn Message** block (no space after the colon). Place it near the price or the **Add to cart** button. The block has no theme editor settings; all text and styling come from Yuko. Once the block is added, the widget editor shows a banner confirming it. ### 3. Verify Open a product page on your live store and check that the message shows the calculated points. ## Available placeholders | Placeholder | Replaced with | | - | - | | `[points_value]` | Total points earned with the purchase. | | `[points_label]` | Your loyalty points label. | | `[points_cash_value]` | Cash value of the points earned. | See the full [placeholder reference](#full-placeholder-reference) below. ## How it works 1. A customer opens a product page that has the block. 2. Yuko reads the selected variant's price and works out the points from your active earn rules. 3. When the customer switches variants, the message updates to the new variant's price. ### Limitations * The block shows only on templates where you've added it. * The widget has no **Custom placement** field; position it with the theme editor. ## Best practices **Keep the message short.** Under 10 words is easy to scan on a busy product page. **Use Custom CSS sparingly.** Small spacing or font tweaks are usually enough to match your theme. ## FAQs Make sure the **Yuko:Product Earn Message** block is added to the product template you're viewing, and that the widget toggle is on in **Loyalty → Widgets**. No. It's built for product detail templates. Yes. Use the **Editing language** picker at the top of the widget editor to set the text for each language published in your store. ## Full placeholder reference Placeholders are written in square brackets, for example `[points_label]`. Each text field's help text in the widget editor lists the placeholders that field supports. **Available in every storefront widget text** | Placeholder | Replaced with | | - | - | | `[points_label]` | Your points label from **Loyalty → Settings** (singular or plural, e.g. *point* / *points*). | | `[point_balance]` | The customer's current points balance. | | `[points_cash_value]` | What the customer's balance is worth in your store currency, based on your points-to-cash conversion rate. | | `[store_name]` | Your store name. | **Widget-specific placeholders** | Placeholder | Replaced with | Used in | | - | - | - | | `[points_value]` | Points the customer can earn on this product, cart or order. | Product page, Cart earn, Checkout earn, Order status earn | | `[first_name]` | The customer's first name (logged-in customers only). | Cart redeem greeting, Loyalty Nudges | | `[customer_name]` | The customer's full name (logged-in customers only). | Loyalty Nudges | | `[points_needed]` | How many more points the customer needs for a reward. | Insufficient-points text (Cart redeem, Loyalty Nudges) | | `[expiration_date]` | The expiry date of an earned reward. Hidden automatically when the reward doesn't expire. `[discount_expiry_date]` works the same way. | Reward expiry text (Cart redeem, Loyalty Nudges, Floating Rewards) | | `[points_to_redeem]` | The number of points the customer chose to redeem. | Checkout redeem summary | | `[discount_value]` | The discount those points unlock. | Checkout redeem summary | | `[tier_name]` | A VIP tier name. | VIP tier text (Floating Rewards) | | `[next_tier]` | The name of the customer's next VIP tier. | VIP progress text | | `[tier_entry_amount]` | The threshold needed to enter a tier. | Cart redeem tier entry text | | `[tier_reach_level]` | The threshold needed to reach a tier. | Floating Rewards VIP text | | `[multiplier_value]` | The points multiplier for a VIP tier (e.g. *2*). Shown only when the multiplier is greater than 1. | Points multiplier benefit text | | `[renewal_date]` | The date a paid membership renews. | Floating Rewards membership text | ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Rewards Landing Page Source: https://docs.yuko.so/onsite-widgets/rewards-landing-page A dedicated loyalty page on your storefront, built from seven Yuko theme blocks, that explains how to join, earn, redeem, reach VIP tiers and become a member. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets → Rewards Landing Page ## Introduction The Rewards Landing Page is the public home of your loyalty program. Yuko creates a Shopify page for it, and you build the page from seven **Yuko** theme blocks: Hero Banner, How It Works, Ways to Earn, Ways to Redeem, VIP Tiers, Membership and FAQ. You write the text in Yuko and style each block in the Shopify theme editor. The widget is marked **Recommended** on the Widgets list. ## What problem this solves Emails, ads, social posts and footer links need somewhere to send people. The landing page explains the program in one place, before customers reach the cart. ## Where it appears * A Shopify page titled **Loyalty Program** at `/pages/loyalty-info-page`, created by Yuko. * Any other page or template where you add the Yuko landing page blocks in the theme editor. ## When to use * You link to your loyalty program from emails, ads or your site footer. * You want one page that covers joining, earning, redeeming, VIP tiers, membership and FAQs. ## Overview * **Seven theme blocks**, each with its own colours, sizes and **Custom CSS** in the theme editor. * **Separate hero text** for visitors (**Anonymous**) and logged-in customers (**When customer is authenticated**). * **Automatic content:** earn rules, rewards, VIP tiers and membership plans come from your live Yuko setup. * **FAQ editor:** add, remove and reorder questions and answers. * **Add Block** buttons that open the theme editor with the right block ready to add. * **Per-language text:** use the **Editing language** picker. ## Before you start Yuko is installed on your Shopify store. The program this widget belongs to is set up and enabled. The widget is switched on with the toggle on its card in Yuko's **Widgets** page (for loyalty widgets, **Shopify admin → Apps → Yuko Loyalty → Loyalty → Widgets**). For storefront widgets, your active theme is an Online Store 2.0 theme that supports app embeds and app blocks. The **Yuko App** embed is turned on in your published theme. See [Theme App Embed](/installation-and-setup/theme-app-embed). ## Setup guide ### 1. Create the page Go to **Apps → Yuko Loyalty → Loyalty → Widgets** and click **Customize** on **Rewards Landing Page**. The first time you open the widget, Yuko asks **Are you sure you want to create a landing page?** Click **Create**. Yuko creates a published Shopify page titled **Loyalty Program** with the handle `loyalty-info-page`. If a page with that handle already exists, Yuko uses it. If you delete the page in Shopify, click **Check landing page** next to the widget's status badge. Yuko confirms whether the page is still there, and offers to create it again the next time you open the widget. ### 2. Write the content in Yuko Each section below matches one theme block. Expand a section to edit its text. | Section | What you set | | - | - | | **Hero Section** | **Anonymous**: title (default *Join Our Rewards Program*), description, join button (*Join Now*) and sign-in button (*Sign In*). **When customer is authenticated**: title (*Welcome Back!*), description, and two buttons (*Earn `[points_label]`* and *Redeem Rewards*). | | **How It Works** | Section title (default *How It Works*) and the title and description for three steps (*Sign up*, *Earn*, *Redeem*). | | **Ways to Earn Points** | Title (default *Ways to Earn `[points_label]`*), description and **Ways to earn — order** (**Booster campaigns first** by default, or **Standard campaigns first**). | | **Ways to Redeem Points** | Title (default *Ways to Redeem `[points_label]`*) and description. | | **VIP Tiers** | Title, description, **Current tier badge text** (default *Current tier*) and **Points multiplier benefit text** (`[multiplier_value]x multiplier`, shown when the multiplier is greater than 1). | | **Paid membership block** | **Title** (default *Become a member & save*), **Benefits title** (*Benefits:*), **Join button** (*Join the club*), and under **Pricing labels**, **Monthly interval label** (*month*) and **Yearly interval label** (*year*). | | **FAQ Section** | **Section Title** (default *Frequently Asked Questions*), **Section Description**, and **FAQ Items**, each with a **Question** and **Answer**. Add items with **Add FAQ Item**, drag to reorder and remove with the delete button. At least one item is required. | | **General Settings** | **Logged-in User Redirect URL**: where logged-in customers go when they click a campaign or reward card. Leave it empty to use the default customer account page. | Click **Save**, then switch the widget on. ### 3. Add the blocks to the page Each section in the editor has an **Add Block** button. It opens the Shopify theme editor on `/pages/loyalty-info-page` with that Yuko block ready to add. Drop the block into a section, then adjust its settings in the theme editor sidebar (see below). Add the remaining blocks in the order you want them on the page and click **Save** in the theme editor. The page uses your theme's page template. If other pages share that template, the blocks appear on them too. To avoid this, create a dedicated page template in your theme, assign it to the **Loyalty Program** page in **Online Store → Pages**, and add the blocks there. ## Theme block settings Every block has a **Custom CSS** field. Colours and sizes are set per block in the theme editor. | Block | Theme editor settings | | - | - | | **Yuko: Hero Banner** | **Background & Colors**: Background Color, Background Image (Desktop), Background Image (Mobile), Background Image Brightness, Card Background, Card Heading and Card Text. **Layout**: Card Position (Left/Center/Right), Card Vertical Position (Top/Center/Bottom), Text Alignment, Card Spacing and Button Alignment. **Buttons**: primary and secondary button background and text colours. **Desktop** and **Mobile**: Section Height, Section Padding, Heading Size and Text Size, plus a mobile **Card Position** (**Below Hero Banner** or **Over Hero Banner**). | | **Yuko: How It Works** | **Colors**: Background, Heading and Text. **Steps**: **Steps Type** (**Numbers** or **Images**), Step 1–3 Image, Number, Step Heading and Step Text colours, Number Size, Step Heading Size, Step Text Size and Step Image Height. | | **Yuko: Ways to Earn** | **Campaign Ordering** (**Ordering Ascending**, **Ordering Descending** or **Recent First**). Background colour and image, Heading and Text colours. **Campaign Cards**: Card Background, Card Border and Card Spacing. **Campaign Text** and **Campaign Icons**: colours and sizes. **Join Button**: background and text colours. | | **Yuko: Ways to Redeem** | **Reward Ordering** (**Ordering Ascending**, **Ordering Descending** or **Recent First**), plus the same colour, card, text, icon and **Join Button** settings as Ways to Earn. | | **Yuko: VIP Tiers** | Background colour and image, Heading and Text. **Tier Cards**: Card Background (Regular Tiers). **Current Tier**: Card Background, Border Color, Badge Background and Badge Text Color. **Tier Text**: tier name and description colours and sizes. **Benefits**: Benefit Text Color and Size, Tick Icon Size and Benefit Item Gap. | | **Yuko: Membership** | Section Background. **Card Styles**: Image, Image Background, Card background color, Section Radius, Title Text Color and Body Text Color. **Button Styles**: Button Color, Button Border Color, Button Text Color and Button Radius. | | **Yuko: FAQ** | Background Color, Heading Color, Question Color, Answer Color and Border Color. | ## How it works 1. Yuko creates the **Loyalty Program** page at `/pages/loyalty-info-page`. 2. You add Yuko blocks to the page in the theme editor. The **Yuko App** embed loads the scripts that fill them. 3. The blocks pull your live earn rules, rewards, VIP tiers and membership plans from Yuko, so the page stays up to date. 4. Visitors see the **Anonymous** hero with join and sign-in buttons. Logged-in customers see the authenticated hero. 5. When a logged-in customer clicks a campaign or reward card, they go to the **Logged-in User Redirect URL**, or to the customer account page if it's empty. ## Examples * **Email destination:** link your welcome email's "See how it works" button to `/pages/loyalty-info-page`. * **Footer link:** add a "Rewards" link in your footer menu that points to the landing page. * **Short page:** use only Hero Banner, Ways to Earn and Ways to Redeem for a quick overview. ## Best practices **Lead with the hero.** Put the Hero Banner first so visitors see the join button straight away. **Answer real questions.** Replace the default FAQ items with the questions your support team actually gets. **Check both hero versions.** Preview the page logged out and logged in. **Link to it everywhere.** Add it to your footer, welcome email and [Floating Rewards](/onsite-widgets/floating-launcher) content. ## FAQs Yuko creates the page at `/pages/loyalty-info-page`. You can also add the Yuko landing page blocks to any other page or template in the theme editor. Click **Check landing page** to confirm it's missing, then reopen the widget. Yuko offers to create the page again. Yes. Every block has colour and size settings plus a **Custom CSS** field in the theme editor. The Membership block shows your paid membership plans. Set up a plan in [Memberships](/memberships/plans) first. Yes. Use the **Editing language** picker at the top of the widget editor to write the text for each of your store's published languages. Campaign and reward names are translated in [Translations](/account/translations). ## Related Floating button and loyalty panel on every page. A dedicated loyalty page built from seven theme blocks. Pinned strip and drawer on every page, ideal for boosters. Show points to earn on product pages. Show points to earn on the cart. Let customers redeem points and apply rewards in the cart. Show points to earn in Shopify Checkout (Shopify Plus). Redeem points and apply rewards in Shopify Checkout (Shopify Plus). Show points earned on the order status page in customer accounts. Show the points balance on the Orders page in customer accounts. Show loyalty details on the Profile page in customer accounts. A full loyalty page inside Shopify customer accounts. Colour palettes for all widgets, and per-language widget text. The Yuko App embed that powers Floating Rewards, Loyalty Nudges and the theme blocks. Add the earn and redeem blocks to Shopify Checkout (Shopify Plus). Add the loyalty blocks and full loyalty page to Shopify customer accounts. Confirm widgets render correctly on the live storefront. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Points Transaction Object Source: https://docs.yuko.so/points-transaction-object Fields returned for a points transaction by the Yuko REST API. A points transaction is a ledger entry that changes a customer's points balance. Points added are a `credit`; points removed are a `debit`. Transactions are returned by [List points transactions](/developer/api/list-points-transactions) (`GET /public/customers/transactions`, requires the `read:transactions` scope). You can add or deduct points with [Create a points transaction](/developer/api/create-a-points-transaction) (`POST /public/customers/transactions`, requires the `write:transactions` scope). ## Properties Unique identifier for the points transaction. Yuko's internal UUID for the customer whose balance changed. This is not the Shopify customer ID you pass as the `customer_id` parameter. Whether points were added or removed. One of `credit`, `debit`. The number of points added or removed. Always positive; use `entry_type` for the direction. For the `store_credit` credit entry recorded when a customer redeems a store credit reward, this is the store credit amount (rounded down to a whole number) rather than points. The action that created the transaction, for example `purchase`, `point_adjustment` (manual and REST API adjustments) or the reward type for redemptions. The current status of the transaction. One of `active`, `on_hold`, `used`, `failed`. A description of the change, if one was provided. Where the transaction came from. Transactions created through the REST API have the source `rest_api`. The date and time the transaction took effect (ISO 8601). The date and time the transaction record was created (ISO 8601). ```json The Points Transaction object theme={null} { "id": "b2c3d4e5-f6a1-7890-bcde-f01234567890", "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76", "entry_type": "credit", "points": 100, "action_type": "purchase", "status": "active", "description": "Points correction", "source": "rest_api", "transacted_at": "2026-02-15T08:30:00+00:00", "created_at": "2026-02-15T08:30:00+00:00" } ``` # Referrals Source: https://docs.yuko.so/referrals/overview Turn customers into advocates with a two-sided referral program. Set referrer and friend rewards, fraud checks, social sharing and UTM tracking in one place. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral ## What is the Referral Program The Referral Program lets your customers (referrers) share a personal link with friends. Both sides get rewarded: * The **friend** gets a welcome reward (a discount code) when they open the link and enter their details. * The **referrer** gets their reward once the friend places a paid order using that discount code. It isn't a separate app. Referrals sit alongside your loyalty program and use the same customers, points balance and storefront widgets. ## Who it's for * Brands with strong word of mouth that want to make it repeatable. * High-AOV or considered-purchase stores, where a personal recommendation carries weight. * Stores that want to lower acquisition costs by rewarding existing customers. ## The Referral menu The **Referral** section of the Yuko admin has three tabs: | Tab | What you do there | | - | - | | **Program** | Turn the program on, set the referrer and friend rewards, and configure the landing URL, social sharing, fraud prevention, auto enrollment and UTM tracking. See [Program Setup](/referrals/program-setup). | | **Widgets** | Configure the storefront and post-purchase referral widgets. See [Referral widgets](/referrals/widget). | | **Emails** | Edit the referral emails. See [Referral emails](/emails/referral-emails). | ## How it fits together ``` Referrer gets a referral link ─→ Shares it ─→ Friend opens the link │ ▼ Friend Welcome Popup: friend enters email │ ▼ Friend gets a discount code (friend reward) │ ▼ Friend places a paid order with that code │ ▼ Referrer gets their reward (discount, points or store credit) ``` The referrer reward and the friend reward are set separately, so you can pick what suits each side. See [Reward Types](/referrals/reward-types). ## Get started Open **Referral → Program**. The **Quick Start** card walks you through **Set up referrer reward**, **Set up friend reward** and **Enable referral popup**. Check the landing URL, sharing channels and fraud prevention in [Program Setup](/referrals/program-setup). Enable the **Friend Welcome Popup** so friends can claim their reward, then add a way for customers to get their link, such as the **Post-Purchase Widget** or the **Referral Landing Page**. See [Referral widgets](/referrals/widget). ## Recommended reading Rewards, landing URL, sharing, fraud prevention and UTM tracking. Pick the right reward for the referrer and the friend. Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup. The emails sent to referrers and friends. Talk to our team for personalised setup help. **Time:** 30 minutes Visit our support hub for help articles, live chat and ticket submission. Documentation across loyalty, referrals, memberships and more. Add Yuko to your Shopify store from the Shopify App Store. # Program Setup Source: https://docs.yuko.so/referrals/program-setup Turn on the referral program and configure rewards, the landing URL, social sharing, fraud prevention, auto enrollment and UTM tracking. **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Program ## Introduction The **Program** tab is where you configure the whole referral program: rewards for both sides, where referral links land, which sharing channels customers see, and how Yuko blocks fraudulent referrals. ## What problem this solves Running referrals usually means combining a referral app, a discount tool and a tracking setup. The Program tab covers all three. Yuko creates the Shopify discount codes, tracks referral links with a UTM campaign, and checks every claim against your fraud rules. ## When to use * When you launch the referral program. * When you change reward values or sharing channels. * When you want to tighten fraud controls. ## Overview The Program tab has these sections: | Section | What it controls | | - | - | | **Referrals Program Status** | Turns the program on or off. | | **Quick Start** | Setup checklist: **Set up referrer reward**, **Set up friend reward**, **Enable referral popup**. | | **Referral Rewards** | The **Referrer Reward** and the **Friend Reward**. | | **Referrals Landing URL** | The page a referral link opens. | | **Social Sharing Settings** | Which share channels customers see, and the pre-filled messages. | | **Fraud Prevention** | **IP Address Match** and **Block Self-Referrals**. | | **Auto Enrollment** | **Enroll on first point earned**. | | **UTM Tracking** | The **UTM Campaign** value added to referral links. | ## Before you start Yuko is installed on your Shopify store. See [Install Yuko on Shopify](/installation-and-setup/install-on-shopify). The **Yuko App** embed is turned on in your theme, so the Friend Welcome Popup can open. See [Theme App Embed](/installation-and-setup/theme-app-embed). You've decided what each side gets. See [Reward Types](/referrals/reward-types). ## Setup guide ### 1. Turn on the program In your Shopify admin, go to **Apps → Yuko Loyalty → Referral → Program**. In **Referrals Program Status**, switch the toggle on. The card shows "This program is currently enabled". If you later switch it off, Yuko asks you to confirm in a **Disable Referrals Program** dialog. ### 2. Set up the rewards In **Referral Rewards**, click **Add Reward** on the **Referrer Reward** card (or **Change Reward** to replace the current one). Pick a reward type and fill in the configuration page. See [Reward Types](/referrals/reward-types). Do the same on the **Friend Reward** card. On a new install, Yuko seeds both rewards as an **Amount Discount** of 10 in your store currency: "Referral reward" (coupon prefix `YRA`) for the referrer and "Welcome reward" (coupon prefix `YRF`) for the friend. Change them to suit your store. ### 3. Set the landing URL In **Referrals Landing URL**, fill in **Referrals Landing URL Path**, for example `/collections/best-sellers` or `/pages/welcome`. If you leave it blank, referral links open your homepage. ### 4. Choose the sharing channels In **Social Sharing Settings**, tick the channels customers can share through: **Twitter**, **Facebook**, **Email** and **Whatsapp**. Each ticked channel shows its message fields: * **Twitter**: **Message to tweet** * **Email**: **Email Subject** and **Email Body** * **Whatsapp**: **Message to Whatsapp** Use `[shop_name]` for your store name and `[referral_link]` for the customer's referral link. The Email Subject supports `[shop_name]` only. Facebook doesn't let third-party apps pre-fill share messages, so there's no message field for Facebook. Customers write their own message when they share. ### 5. Configure fraud prevention Stops customers from using their own referral link. It's **on by default**. Yuko blocks the claim when the friend's email matches the referrer's, or when the friend resolves to the same Shopify customer as the referrer. Blocks the claim when the friend and the referrer share the same IP address. This toggle is available on select plans. ### 6. Configure auto enrollment Turn this on to enroll a customer in the referral program automatically the first time they earn loyalty points. Enrolled customers get a referral code and link without having to request one. Customers who aren't enrolled can still join by clicking **Get referral link** in a referral widget. ### 7. Set the UTM campaign In **UTM Tracking**, set **UTM Campaign**. This is the `utm_campaign` value added to every referral link. If you leave it empty, Yuko uses `yuko_referral_program`. Only the campaign value is configurable. A referral link looks like this: ``` https://your-store.com/?yuko_referral=

&utm_campaign=yuko_referral_program
```

### 8. Save

Click **Save** in the save bar.

## How it works

1. A customer becomes a referrer, either automatically (if **Enroll on first point earned** is on) or by clicking **Get referral link** in a referral widget. Yuko gives them a unique referral code and link.
2. The referrer shares the link through a widget or one of the enabled channels.
3. A friend opens the link. The **Friend Welcome Popup** asks for their details (at least an email).
4. Yuko checks the claim:
   * The referral code is valid and the referrer isn't blocked.
   * **Block Self-Referrals** and **IP Address Match** rules pass (when turned on).
   * The friend has no previous orders and hasn't already received a friend reward.
5. If the claim passes, Yuko creates the friend's discount code and shows it in the popup.
6. When the friend places a paid order using that code, Yuko issues the referrer reward and counts the referral as successful.

### Limitations

* The referrer is rewarded only for a paid order that uses the friend's referral discount code.
* Friends must be new customers. A friend with an existing order can't claim a friend reward.
* Each customer can receive only one friend reward.
* Referral links rely on the `yuko_referral` URL parameter, so the friend must open the full link.

## Examples

* Referrer gets 500 points (**Earn Points**); friend gets \$10 off (**Amount Discount**), with **Block Self-Referrals** and **IP Address Match** on.
* Referrer gets \$20 **Store Credit**; friend gets 15% off (**Percentage Off**), with the landing URL set to `/collections/best-sellers`.

## Best practices

**Test the whole flow before you promote it.** Share a link, open it in a private window, claim the friend reward, place an order with the code, and check that the referrer is rewarded.
**Keep Block Self-Referrals on.** It's the main guard against customers rewarding themselves.
**Promote referrals in your post-purchase moments.** The Post-Purchase Widget and your order emails reach customers when they're most engaged.

## FAQs


  
    When the friend places a paid order that uses the friend's referral discount code. Orders without that code don't count as referral orders.
  

  
    Not while **Block Self-Referrals** is on. Yuko blocks claims where the friend's email or Shopify customer matches the referrer. Turn on **IP Address Match** too if you want to block claims from the referrer's IP address.
  

  
    No. Only **UTM Campaign** is configurable. Links copied or shared from the Referral Landing Page also add `utm_source=yuko_referral`, a `utm_medium` for the share channel (for example `copy_link`) and `utm_content` set to the referral code.
  

  
    In the referral widgets (the Post-Purchase Widget and the Referral Landing Page), and in the referral sections of the Floating Rewards launcher and the customer account page. See [Referral widgets](/referrals/widget).
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Reward Types
Source: https://docs.yuko.so/referrals/reward-types

The reward types available to referrers and friends, and every setting on the reward configuration page.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Program → Referral Rewards


## Introduction

The referral program has two independent rewards: the **Referrer Reward** (for the customer who shares) and the **Friend Reward** (for the new customer who opens the link). You can give each side a different kind of reward.

## What problem this solves

Referrers and friends want different things. A referrer may value points or store credit they can use later. A friend needs a clear reason to place a first order. Setting the two rewards separately lets you match each side.

## Available reward types

| Reward type | Referrer | Friend | What the customer gets |
| - | - | - | - |
| **Amount Discount** | Yes | Yes | A discount code for a fixed amount off. |
| **Percentage Off** | Yes | Yes | A discount code for a percentage off. |
| **Free Shipping** | Yes | Yes | A free-shipping discount code. |
| **Free Product** | Yes | Yes | A discount code that makes a chosen product free. |
| **Earn Points** | Yes | No | Loyalty points added to the referrer's balance. |
| **Store Credit** | Yes | No | Shopify store credit added to the referrer's account. |

Friend rewards are always discount codes. The friend sees the code in the Friend Welcome Popup and can apply it at checkout.


  **Earn Points** needs your loyalty program to be enabled. If it isn't, no points are issued.


## Configuration options

When you click **Add Reward** (or **Change Reward**) on a reward card, you pick a type and then fill in its configuration page. Which settings appear depends on the type.

| Setting | Shown for | What it does |
| - | - | - |
| **Title** | All types | The reward name customers see, for example `$5 off coupon`. Referral widgets show it through the `{{friend_reward}}` and `{{referrer_reward}}` shortcodes. |
| **Value** / **Reward value** | All types except Free Shipping and Free Product | The amount, percentage or number of points. |
| **Applies to** | Amount Discount, Percentage Off | **All products**, **Specific collections** or **Specific products**. |
| **Only apply discount once per order** | Amount Discount applied to specific collections or products | If not selected, the amount comes off each eligible item. |
| **Select product** | Free Product | The product given as the reward. |
| **Shipping restrictions** | Free Shipping | **Countries** (**All countries** or **Selected countries**) and **Exclude shipping rates over a certain amount** with a **Maximum shipping rate**. |
| **Coupon prefix** | Discount-code types | Text added to the start of each generated code (letters and numbers, up to 8 characters). |
| **Coupon expiry** | Discount-code types | Turn on to make the code expire after a **Duration** in Days, Weeks, Months or Years. |
| **Reward expires** | Earn Points, Store Credit | Turn on to make the points or store credit expire after a set duration. |
| **Who can use this reward** | Referrer discount-code types | **Limit the reward usage only to the recipient** restricts the code to the referrer's Shopify customer account. |
| **Purchase type** | Amount Discount, Percentage Off, Free Shipping | **One-time purchase**, **Subscription** or **Both**. Subscription options only take effect if your store sells subscriptions. |
| **Minimum purchase requirements** | Discount-code types | **No minimum requirements**, **Minimum purchase amount** or **Minimum quantity of items**. |
| **Combinations** | Discount-code types | Whether the code combines with **Product discounts**, **Order discounts** and **Shipping discounts** (the shipping option isn't shown for Free Shipping rewards). |


  Friend discount codes are always limited to the friend's customer account.


## Decision guidance

### Picking the referrer reward


  
    Good for engagement-led programs. It ties the referrer back into your loyalty program and lets them redeem on any reward.
  

  
    Good for premium brands. It feels like money on file rather than a coupon.
  

  
    Good when you want the referrer to come back and buy again soon.
  

  
    Good when you want a non-cash reward that reads like a gift.
  


### Picking the friend reward


  
    Easy to explain: "Get \$10 off your first order." Add a minimum purchase amount to protect margin.
  

  
    Works well for higher-AOV stores, where 10 to 20% is a meaningful amount.
  

  
    Works where shipping cost is a known reason for abandoned carts.
  

  
    Works for product launches or sample-size items, putting a specific product in the friend's hands.
  


## How it works

* **Friend reward:** Yuko creates the friend's discount code when they claim it in the Friend Welcome Popup. The friend must be a new customer (no previous orders), and each customer can receive only one friend reward.
* **Referrer reward:** Yuko issues it when the friend places a paid order that uses the friend's referral code:
  * Discount-code types create a Shopify discount code for the referrer.
  * **Earn Points** credits the referrer's points balance.
  * **Store Credit** adds Shopify store credit to the referrer's account.
* Expiry is counted from the moment the reward is issued.

### Limitations

* Friends can't receive points or store credit; friend rewards are discount codes only.
* There is one referrer reward and one friend reward per program.
* There's no cap on how many successful referrals one referrer can be rewarded for.

## Examples

| Referrer reward | Friend reward | Why it works |
| - | - | - |
| 500 points (**Earn Points**) | $10 off (**Amount Discount**) with a $50 minimum | Pulls the referrer back into the loyalty program and protects margin on the friend's order. |
| \$20 **Store Credit** | 15% off (**Percentage Off**) | Discount-led, with a premium feel for the referrer. |
| **Free Product** | **Free Shipping** | Non-cash on both sides; feels like a gift. |

## Best practices

**Don't make either side feel cheap.** A \$1 discount looks like an afterthought.
**Keep the two rewards in proportion.** A big friend reward with a tiny referrer reward reduces the referrer's motivation to share.
**Give each reward a clear Title.** The title is what customers see in the referral widgets.

## FAQs


  
    No. Friend rewards are discount codes only. Friends earn points the usual way after their first order.
  

  
    No. Each program has one referrer reward and one friend reward. To change one, click **Change Reward** on its card.
  

  
    No. There's no per-referrer cap.
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Referral Widgets
Source: https://docs.yuko.so/referrals/widget

An overview of the referral widgets, the theme block and the checkout block that let customers get their referral link and let friends claim their reward.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Widgets


## Introduction

Referral widgets are the storefront surfaces of your referral program. They let customers get and share their referral link, and let friends claim their welcome reward when they open a link.

## The widgets

The **Widgets** tab lists three widgets. Each card has a toggle to turn it on or off, and opens its own editor.

| Widget | What it does | Where it appears | Storefront block |
| - | - | - | - |
| [**Post-Purchase Widget**](/referrals/widgets/post-purchase) | Invites customers to get their referral link right after they buy. | Thank-you page and order status page. | **Yuko Referral Signup** (checkout and customer account UI extension). |
| [**Referral Landing Page**](/referrals/widgets/landing-page) | A dedicated page where visitors sign up for a referral link and logged-in customers copy theirs. | A Shopify page, created for you at `/pages/referral-info-page`. | **Yuko: Referral Signup** (theme app block). |
| [**Friend Welcome Popup**](/referrals/widgets/friend-welcome-popup) | The popup friends see when they open a referral link. It collects their details and reveals the friend discount code. | Any storefront page opened from a referral link. | No block. It loads through the **Yuko App** embed. |

Referral links can also be shared from the referral section of the [Floating Rewards launcher](/onsite-widgets/floating-launcher) and the [customer account page](/onsite-widgets/customer-account-page). Those are configured with the loyalty widgets.

## Storefront blocks

### Yuko: Referral Signup (theme app block)

The theme app block behind the **Referral Landing Page**. Add it to any page template in the theme editor. It has its own theme-editor settings:

* **Content:** **Show Banner Image**, **Banner Image**, **Image Position (Desktop)** (Top, Left, Right; default Left), **Text Alignment** (Left, Center, Right; default Center).
* **Colors:** **Background**, **Text**, **Button Background**, **Button Text**, **Border**, **Error Text**.
* **Typography:** **Heading Size** (16 to 48, default 28) and **Text Size** (12 to 24, default 16).
* **Spacing & Shape:** **Border Width** (0 to 5, default 1) and **Corner Radius** (0 to 24, default 8).
* **Custom CSS**.

The text lives in Yuko, under **Referral → Widgets → Referral Landing Page**.

### Yuko Referral Signup (checkout and customer account block)

The extension block behind the **Post-Purchase Widget**. It has two targets:

* The **Thank you** page in the checkout editor.
* The **Order status** page in the customer accounts editor.

Its text lives in Yuko, under **Referral → Widgets → Post-Purchase Widget**. Its look follows Shopify's checkout and customer account styling.

## Before you start

The referral program is enabled and both rewards are set in **Referral → Program**. Widgets stay hidden until a friend reward exists.
The **Yuko App** embed is turned on in your theme. See [Theme App Embed](/installation-and-setup/theme-app-embed).

## Common editor features

* **Editing language:** each widget editor has a language picker, so you can enter text for every language published in your Shopify store.
* **Reward shortcodes:** text fields accept `{{friend_reward}}` and `{{referrer_reward}}`. They're replaced with the **Title** of the friend and referrer rewards.
* **Form fields:** the Referral Landing Page and Friend Welcome Popup let you choose which fields the form collects (**First Name**, **Last Name**, **Phone**, **Marketing Consent**; **Email** is always included).
* **Preview:** each editor shows a live preview of the widget's states.

## Recommended setup


  
    Without it, friends who open a referral link can't claim their reward. It's the **Enable referral popup** step in the Program tab's Quick Start.
  

  
    Turn on the **Post-Purchase Widget**, the **Referral Landing Page**, or both.
  

  
    Get a link as a customer, open it in a private window, and claim the friend reward.
  


## FAQs


  
    Check that the referral program is enabled, a friend reward is set, the widget's toggle is on, and its block (or the Yuko App embed) is added to your theme, checkout or customer accounts.
  

  
    The Friend Welcome Popup has a **Styles** tab in Yuko. The Referral Landing Page is styled in the theme editor through the **Yuko: Referral Signup** block. The Post-Purchase Widget follows Shopify's checkout styling.
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Friend Welcome Popup
Source: https://docs.yuko.so/referrals/widgets/friend-welcome-popup

The popup friends see when they open a referral link. It collects their details and reveals their welcome discount code.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Widgets → Friend Welcome Popup


## Introduction

The **Friend Welcome Popup** is what a friend sees after clicking a referral link. In two steps, it asks for their details, then reveals their friend reward code with a button to apply it.

## What problem this solves

This popup is how friends claim their reward. Without it, a friend who opens a referral link gets no discount code, and the referrer can't be rewarded. That's why turning it on is a Quick Start step (**Enable referral popup**).

## Where it appears

* On any storefront page opened from a referral link (a URL that contains `yuko_referral`). It opens on the landing page set in **Referral → Program → Referrals Landing URL**.
* It loads through the **Yuko App** embed. There's no block to add.

## Overview

* **Step 1: Input Screen** collects the friend's details.
* **Step 2: Reward Screen** shows the discount code and an apply button.
* A **Styles** tab with colours, sizes and Custom CSS.
* An optional hero image (desktop only).

## Before you start

The referral program is enabled and a friend reward is set in **Referral → Program**. The popup doesn't open without a friend reward.
The **Yuko App** embed is turned on in your theme. See [Theme App Embed](/installation-and-setup/theme-app-embed).

## Setup guide

### 1. Configure the content


  
    Go to **Referral → Widgets** and open **Friend Welcome Popup**. The **Configuration** tab opens first.
  

  
    | Field | Default |
    | - | - |
    | **Enable Hero Image** / **Hero Image** | On, with a default banner image. Recommended size 800×1000px (JPG, PNG or GIF). Shown on desktop only. |
    | **Label** | `Friend Invitation` |
    | **Heading** | `Unlock your offer!` |
    | **Message** | `Enter your email to reveal your discount code.` |
    | **Form** | First Name, Last Name and Your email. **Email** is always included. You can also add **Phone** or **Marketing Consent** with **Add form field**. |
    | **Button Text** (max 30 characters) | `Unlock Offer` |

    For each form field you can edit the **Label** and **Placeholder**, mark it as a **Required field**, show or hide it, and drag fields into a new order.
  

  
    | Field | Default |
    | - | - |
    | **Label** | `Your Reward` |
    | **Heading** | `Welcome! Enjoy {{friend_reward}}` |
    | **Message** | `Use the code below at checkout to get {{friend_reward}}.` |
    | **Button Text** (max 30 characters) | `Apply at checkout` |
  

  
    Set **Success message (toast)**, shown after the friend clicks the apply button and the discount is applied. Default: `Your discount code has been revealed! Use it at checkout.`
  


Headings and messages accept `{{friend_reward}}` and `{{referrer_reward}}`, which are replaced with your reward titles. The default Step 2 text uses `{{friend_reward}}`, so it stays accurate when you change the reward.

### 2. Style the popup

On the **Styles** tab, set the font size and weight, heading and label font sizes, padding, border radius, border width and colour, background and text colours, button colours, success and error colours, and optional **Custom CSS**.

### 3. Save and enable

Click **Save**, then switch the toggle next to the widget title on.

### 4. Verify

Copy a customer's referral link and open it in a private window. The popup should open. Enter a new email address and check that a discount code appears and that **Apply at checkout** applies it.

## How it works

1. A friend opens a referral link. The Yuko App embed sees the referral code in the URL and opens the popup.
2. The friend fills in the form and clicks the Step 1 button.
3. Yuko checks the claim against your fraud rules and confirms the friend is a new customer, then creates their discount code.
4. Step 2 shows the code. Clicking the apply button adds the code to the cart and shows the success message.
5. When the friend places a paid order with that code, the referrer is rewarded.

If the claim fails (for example, a self-referral, or a friend who already has orders), the popup shows an error and no code is issued.

## Best practices

**Use `{{friend_reward}}` in the heading** so the popup always matches the real reward.
**Ask only for what you need.** Email is required. Every extra field lowers completion.

## FAQs


  
    Check that the widget toggle is on, a friend reward is set, the referral program is enabled, and the Yuko App embed is on in your live theme.
  

  
    No. Friends must have no previous orders, and each customer can receive only one friend reward.
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Referral Landing Page
Source: https://docs.yuko.so/referrals/widgets/landing-page

A dedicated referral page where visitors sign up for a referral link and logged-in customers copy and share theirs.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Widgets → Referral Landing Page


## Introduction

The **Referral Landing Page** is a dedicated page for your referral program. Visitors can sign up for a referral link, and logged-in customers can copy and share theirs. On the storefront, it's rendered by the **Yuko: Referral Signup** theme app block.

## What problem this solves

Customers can't refer friends if they can't find their link. A dedicated page gives you one URL to promote in emails, ads and your navigation, and it works for both guests and logged-in customers.

## Where it appears

* A Shopify page Yuko creates for you: **Referral Program**, at `/pages/referral-info-page`.
* Any other page template where you add the **Yuko: Referral Signup** block.

## Overview

* **Guest View** and **Logged In View**, each with its own text.
* A configurable sign-up form for guests.
* Optional social share buttons.
* No Styles tab in Yuko. Colours, fonts, banner image and Custom CSS are set on the theme block.

## Before you start

The referral program is enabled and a friend reward is set in **Referral → Program**.
The **Yuko App** embed is turned on in your theme. See [Theme App Embed](/installation-and-setup/theme-app-embed).

## Setup guide

### 1. Create the page


  
    Go to **Referral → Widgets** and open **Referral Landing Page**.
  

  
    If your store has no referral landing page yet, Yuko opens a **Create referral landing page** dialog. Click **Create** to add a Shopify page titled **Referral Program** at `/pages/referral-info-page`.
  


Once the page exists, a **Check landing page** button appears next to the widget title. Use it to confirm the page is still in Shopify, for example if someone may have deleted it.

### 2. Edit the content


  
    | Field | Default |
    | - | - |
    | **Page Title** | `Refer a friend. You & your friend both get rewarded` |
    | **Page Subtitle** | `Get your personalized referral link. Once a friend uses your link and makes a successful purchase, you'll get a reward for your next order with us.` |
    | **Form** | **First Name**, **Last Name**, **Email** and **Marketing Consent** (`I agree to receive marketing emails`). **Email** is always included. Add **Phone** with **Add form field**. |
    | **Button Text** (submit button, max 30 characters) | `Submit` |

    For each form field you can edit the **Label** and **Placeholder**, mark it as a **Required field**, show or hide it, and drag fields into a new order.
  

  
    | Field | Default |
    | - | - |
    | **Page Title** | `Earn for every friend you refer` |
    | **Page Subtitle** | `Copy and share your personalized referral link with your friends` |
    | **Copy Button Text** (max 30 characters) | `Copy` |
    | **Get Link Button Text** (shown before the link is loaded, max 30 characters) | `Get referral link` |
  

  
    Turn on **Enable Social Share** to show share buttons, and set **Or share via text** (default `Or share via:`). Only the channels enabled in **Referral → Program → Social Sharing Settings** appear on the storefront. The preview always shows every channel.
  

  
    Click **Save**, then switch the toggle next to the widget title on.
  


Titles and subtitles accept `{{friend_reward}}` and `{{referrer_reward}}`, which are replaced with your reward titles.

### 3. Add or style the block in your theme

The page Yuko creates is ready to use. To add the widget to another page, or to style it, click **Add block** in the widget editor, or follow these steps:


  
    Theme blocks get their content from Yuko's storefront script, which loads through the **Yuko App** app embed. If you haven't already, enable it in **Online Store → Themes → Customize → App embeds**. See [Theme App Embed](/installation-and-setup/theme-app-embed).
  

  
    In your Shopify admin, go to **Online Store → Themes**, find your active theme, and click **Customize**.
  

  
    Use the template selector at the top to open the page where this widget should appear (Product, Cart, a page template, and so on).
  

  
    Click **Add block** in the section where you want the widget. Under **Apps**, select the Yuko block named for this widget (block names start with **Yuko:**).
  

  
    Drag the block to your preferred position and click **Save**.
  


Choose the **Yuko: Referral Signup** block. Its theme-editor settings cover the banner image and position, text alignment, colours, heading and text size, border width, corner radius and Custom CSS. See [Referral widgets](/referrals/widget#yuko-referral-signup-theme-app-block).

### 4. Verify

Open `/pages/referral-info-page` in a private window and sign up with a test email. Then log in as a customer and check that the Logged In View shows a referral link.

## How it works

1. A guest fills in the form and submits it. Yuko enrolls them as a referrer and shows their link.
2. A logged-in customer clicks **Get referral link** (or sees their existing link) and copies it.
3. If social sharing is on, customers can share through your enabled channels.

## Best practices

**Link to the page from your navigation and emails.** A dedicated URL is easy to promote.
**Keep the form short.** Email alone is enough to create a referral link.

## FAQs


  
    Open the widget in Yuko. If the page no longer exists, the **Create referral landing page** dialog appears again.
  

  
    This widget is styled in the Shopify theme editor, through the **Yuko: Referral Signup** block settings.
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Post-Purchase Widget
Source: https://docs.yuko.so/referrals/widgets/post-purchase

Invite customers to get and share their referral link on the thank-you and order status pages, right after they buy.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Referral → Widgets → Post-Purchase Widget


## Introduction

The **Post-Purchase Widget** asks customers to refer a friend straight after checkout. It's the **Yuko Referral Signup** extension block, shown on the thank-you page and on the order status page in customer accounts.

## What problem this solves

Customers are most enthusiastic right after buying. Showing the referral offer at that moment, with a one-click way to get a link, turns that enthusiasm into referrals.

## Where it appears

* The **Thank you** page (`purchase.thank-you.block.render`).
* The **Order status** page in Shopify customer accounts (`customer-account.order-status.block.render`).

## Overview

* Four text fields: title, description and two button labels.
* No Styles tab. The block uses Shopify's checkout and customer account styling.
* A customer who isn't a referrer yet sees **Get referral link**. Clicking it enrolls them and shows their link with a copy button. Existing referrers see their link straight away.

## Before you start

The referral program is enabled and a friend reward is set in **Referral → Program**. The widget stays hidden without a friend reward.
For the order status page, your store uses Shopify customer accounts (**Settings → Customer accounts**).

## Setup guide

### 1. Configure the widget in Yuko


  
    Go to **Referral → Widgets** and open **Post-Purchase Widget**.
  

  
    | Field | Default |
    | - | - |
    | **Title** | `Refer a friend & get rewarded!` |
    | **Description** | `Give your friends {{friend_reward}} and get {{referrer_reward}} for each successful referral.` |
    | **Copy Button Text** (shown once the link is displayed, max 30 characters) | `Copy Link` |
    | **Get Link Button Text** (shown before the link is loaded, max 30 characters) | `Get referral link` |

    In **Title** and **Description**, use `{{friend_reward}}` and `{{referrer_reward}}` to insert the reward titles, so the text stays in sync with your rewards.
  

  
    Click **Save**, then switch the toggle next to the widget title on. The badge changes to **Active**.
  


### 2. Add the block to the thank-you page


  
    In your Shopify admin, go to **Settings → Checkout** and click **Customize**.
  

  
    Use the page selector at the top to switch to **Thank you**.
  

  
    Click **Add app block**, choose **Yuko Referral Signup**, position it and click **Save**.
  


### 3. Add the block to the order status page


  
    In your Shopify admin, go to **Settings → Customer accounts** and click **Customize**.
  

  
    Use the page selector at the top to open the page where the block should appear (Order status, Orders, or Profile).
  

  
    Click **Add app block** and choose the Yuko block for this widget (for example **Yuko Order status earned points**, **Yuko Order index points display** or **Yuko Profile loyalty program**).
  

  
    Position the block where customers will see it and click **Save**.
  



  Customer account blocks only work with Shopify's **new customer accounts**. Check that they're turned on in **Settings → Customer accounts**.


On the **Order status** page, add the **Yuko Referral Signup** block.

### 4. Verify

Place a test order and check that the widget appears on the thank-you page. Click **Get referral link**, then copy the link and open it in a private window to check that the Friend Welcome Popup appears.

## How it works

1. The block checks that the referral module is on, a friend reward exists and the widget is enabled.
2. If the customer already has a referral code, the block shows their link.
3. Otherwise the block shows **Get referral link**. Clicking it enrolls the customer as a referrer and shows the new link.
4. The customer copies the link and shares it.

### Limitations

* The block's look follows Shopify's checkout and customer account styling.
* The order status target needs Shopify customer accounts and a logged-in customer.

## FAQs


  
    Thank-you and order status page blocks don't require Shopify Plus. Checkout-step blocks, such as the loyalty checkout widgets, do.
  

  
    Check that a friend reward is set, the widget's toggle is on, and the **Yuko Referral Signup** block is added to the page you're looking at.
  


## Related


  
    Rewards, landing URL, sharing, fraud prevention and UTM tracking.
  

  
    Pick the right reward for the referrer and the friend.
  

  
    Post-Purchase Widget, Referral Landing Page and Friend Welcome Popup.
  

  
    The emails sent to referrers and friends.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Retrieve a points transaction
Source: https://docs.yuko.so/retrieve-a-points-transaction

How to look up a customer's points transactions with the REST API.

The Yuko REST API doesn't have an endpoint to fetch a single points transaction by ID. To find a transaction, list the customer's transactions with [List points transactions](/developer/api/list-points-transactions).

## Listing a customer's transactions

`GET /public/customers/transactions`

Requires the `read:transactions` scope. See [Scopes](/developer/api/scopes).

* Pass the platform customer ID (for example, the Shopify customer ID) as `customer_id`.
* Optionally filter with `entry_type` (`credit` or `debit`) and page through results with `page` and `per_page` (maximum `100`).
* Results are sorted newest first.

## Matching a transaction you created

When you create a transaction with [Create a points transaction](/developer/api/create-a-points-transaction), the response includes its `transaction_id`. That value matches the `id` of the transaction in the list results.

See the [Points Transaction Object](/points-transaction-object) for every field returned.


# Support
Source: https://docs.yuko.so/support/index

Get help with Yuko — browse articles, chat with our team, or book a setup call.

If you ever need assistance, we're here to help.

## Get help


  
    Help articles, troubleshooting guides and live chat.
  

  
    30 minutes with our team for personalised setup help.
  


You can also start a live chat with our team from inside Yuko (**Shopify admin → Apps → Yuko Loyalty**).

## What to include in a support request

To speed up the back-and-forth, please share:

* Your Shopify store URL.
* The Yuko area you're working in (Loyalty, Referral, Memberships, Workflows, etc.).
* A short description of what you expected vs what you saw.
* A screenshot if relevant.

Our support specialists will get back to you quickly with the guidance you need.




# Third Party Checkout Provider Integration Guide
Source: https://docs.yuko.so/third-party-checkout-integrations

Step-by-step guide for third party checkout providers to integrate Yuko Loyalty into the checkout experience.


  IMPORTANT: This guide is only applicable for checkout providers in Shopify platform


## Overview

When a customer reaches your checkout, this integration lets you show them three things from Yuko — in real time:

| What the customer sees / does | API endpoint |
| - | - |
| Their current points balance | `GET /customers/rewards/redeemable` |
| Rewards available to redeem right now | `GET /customers/rewards/redeemable` |
| Spend their points to get a discount code or store credit | `POST /customers/rewards/redeem` |
| Points they will earn on this purchase | `POST /points/estimate` |

Three API calls. One seamless checkout experience.

***

## How it works

```text theme={null}
Customer reaches checkout
        │
        ▼
Your checkout identifies the customer
(Shopify Customer ID is required for Endpoints 1 & 3)
        │
        ├─────────────────────────────────────────────┐
        ▼                                             ▼
  API Call #1                                  API Call #2
  GET /customers/rewards/redeemable            POST /points/estimate
  Requires Shopify Customer ID                 No customer ID needed       
  Only for logged-in customers                 Works for guests too
        │                                             │
        ▼                                             ▼
  Returns:                                     Returns:
  · Points balance                             · Points earned on this cart
  · Rewards available to redeem
  · Rewards already issued (codes)
        │                                             │
        └────────────────┬────────────────────────────┘
                         ▼
          Your checkout UI renders:
          "You have 650 points"
          "Redeem: $5 off (costs 500 pts)"   ← customer clicks this
          "Unused coupon: YUKO-TVJ-BL1"
          "You'll earn 120 points on this order"
                         │
          Customer clicks "Redeem" on a reward
                         │
                         ▼
                   API Call #3
                   POST /customers/rewards/redeem
                   Sends: customer_id + reward_id
                         │
                         ▼
                   Returns:
                   · New discount code (e.g. YUKO-ABC-123)
                   · Points deducted
                   · Expiry date
                         │
                         ▼
          Your checkout applies the discount code
          Customer completes purchase
```


  All Yuko API calls must be made from your **backend server** — never directly from the customer's browser. See [Security Rules](#security-rules) for details.


***

## Before you start

### What the merchant needs to do

The merchant must have Yuko installed on their Shopify store. Once installed:


  
    Go to the merchant's **Shopify Admin Dashboard**.
  

  
    Click **Apps → Yuko Loyalty**.
  

  
    Navigate to **Integrations → REST API** and click **Create new key**.
  

  
    Choose **Custom Key** and give the key **Read/Write Access** on **Rewards** (`write:rewards`, needed to redeem) and **Read Access** on **Points** (`read:points`, needed for the estimate).
  

  
    Copy the API key and share it securely with your team. It looks like this:

    ```text theme={null}
    py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```
  



  Each merchant generates their own API key. If you are integrating across multiple merchants, each one will have a different key.


### What your team needs

* The customer's **Shopify Customer ID** at checkout time — required for Endpoint 1, only available when the customer is logged in
* **Shopify Product IDs and Variant IDs** for every item in the cart — required for Endpoint 2

***

## Authentication

Yuko uses **Bearer Token Authentication**. Every API request must include the merchant's API key in the `Authorization` header.

```text theme={null}
Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

This header is required on **every single request** — no exceptions.


  Full authentication details are in the [Authentication reference](/developer/api/authentication).


### Base URL

All Yuko API requests start with:

```text theme={null}
https://api.yukoapp.com/api/v1/public
```

### General rules

* Always use **HTTPS**
* Always set `Content-Type: application/json` on POST requests
* All responses are JSON
* Successful responses wrap data inside a `"data"` key
* Error responses include an `"error"` object with `code` and `message`

See the [API Introduction](/developer/api/introduction) for a full overview of request and response formats.

***

## Endpoint 1: Get points balance and redeemable rewards

This is the primary endpoint for your checkout loyalty panel. One call returns everything:

* The customer's current points balance
* All rewards they can redeem (with a flag showing if they have enough points for each)
* Rewards already issued to the customer (with their discount codes and status)


  `/customers/rewards/redeemable` is a single endpoint that covers both the points balance **and** the full rewards list. You do not need a separate "get balance" call.


Full API reference → [`GET /customers/rewards/redeemable`](/developer/api/get-redeemable-rewards)

### Request

```text theme={null}
GET https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable
```

Requires the `read:rewards` scope (or `write:rewards`). The merchant configures this in **Shopify Admin → Apps → Yuko Loyalty → Integrations → REST API**. See [Scopes](/developer/api/scopes).

### Query parameters


  The Shopify Customer ID of the logged-in customer, for example `9049402769586`. This is mandatory — do not call this endpoint for guest checkouts.


### Example request

```bash theme={null}
curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Example response

```json 200 theme={null}
{
  "data": {
    "points_balance": 650,
    "rewards": [
      {
        "id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
        "name": "$5 off your next order",
        "description": "Redeem 500 points for a $5 discount.",
        "reward_type": "fixed",
        "points_cost": 500,
        "reward_rule": {
          "points_required": 500,
          "value": 5
        },
        "icon": null,
        "can_redeem": true,
        "points_needed": 0
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "10% off your next order",
        "description": "Redeem 1000 points for 10% off.",
        "reward_type": "percentage",
        "points_cost": 1000,
        "reward_rule": {
          "points_required": 1000,
          "value": 10
        },
        "icon": null,
        "can_redeem": false,
        "points_needed": 350
      }
    ],
    "customer_rewards": [
      {
        "id": "1fd80ced-326f-4082-951b-21a38632a603",
        "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
        "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
        "reward_type": "fixed",
        "status": "active",
        "discount_code": "YUKO-TVJ-BL1",
        "points_used": 500,
        "expires_at": "2026-06-01T00:00:00+00:00",
        "used_at": null,
        "created_at": "2026-02-15T08:30:00+00:00"
      }
    ]
  }
}
```

### Response fields


  
    
      The customer's current redeemable points balance. Always `0` for customers who are excluded (banned) from the loyalty program. Display this prominently at the top of your loyalty panel.
    

    
      All active rewards for the online store (point-of-sale rewards are excluded), enriched with affordability data for this specific customer.

      
        
          Unique ID of the reward.
        

        
          The reward name to display to the customer.
        

        
          Optional longer description of the reward.
        

        
          The type of reward. One of `fixed`, `percentage`, `free_shipping`, `free_product`, `store_credit`.
        

        
          How many points the customer must spend to redeem this reward (taken from `reward_rule.points_required`).
        

        
          The reward configuration, returned as stored. Structure varies by `reward_type`. Every reward includes `points_required`; `fixed`, `percentage` and `store_credit` rewards include `value` (the amount, percentage or credit amount).
        

        
          The reward's icon, or `null` if none is set. Contains `source` (`default` or `custom`), `slug`, `id` and `url`.
        

        
          `true` if the customer has enough points. `false` if not.
        

        
          How many more points the customer needs. Always `0` when `can_redeem` is `true`.
        
      
    

    
      Every reward already issued to the customer, newest first, in any status (including used and expired ones) and from any source (points redemptions as well as VIP tier, referral and membership rewards, so `reward_id` isn't always a catalogue reward ID). Filter on `status === "active"` to find codes the customer can still apply. Each item is a [Customer Reward Object](/customer-reward-object).

      
        
          The actual coupon code (e.g. `YUKO-TVJ-BL1`). This is a standard Shopify discount code — pass it directly through your checkout discount flow.
        

        
          Current status. Only show coupons where `status === "active"`. One of `active`, `used`, `inactive`, `expired`, `deleted`, `revert`.
        

        
          When this coupon expires. `null` means no expiry.
        

        
          `null` if the coupon has not been used yet.
        

        
          How many points were spent to create this coupon.
        
      
    
  


### Display logic

```text theme={null}
If points_balance > 0:
  Show: "You have {points_balance} points"

For each reward in rewards[]:
  If can_redeem === true  → Show active "Redeem" button: "{name} — {points_cost} pts"
  If can_redeem === false → Show greyed out: "{name} — earn {points_needed} more points"

For each item in customer_rewards[] where status === "active":
  Show: "You have an unused reward: {discount_code}"
```

***

## Endpoint 2: Points estimate at checkout

This endpoint tells the customer how many loyalty points they will **earn** when they complete this purchase.

No Shopify Customer ID is required (you still need the API key), so it works for both logged-in customers and guests.


  The request carries product and variant IDs only, with no prices or quantities, so the cart amount Yuko calculates with is always `0`. As a result the endpoint currently returns `points_earned: 0` for every request. With the display logic below, the earn message stays hidden. Confirm it returns non-zero values for the merchant's earn rules before you rely on it.


Full API reference → [`POST /points/estimate`](/developer/api/checkout-points-estimate)

Requires the `read:points` scope. See [Scopes](/developer/api/scopes).

### Request

```text theme={null}
POST https://api.yukoapp.com/api/v1/public/points/estimate
```

### Request body


  Optional. Include only if the customer is logged in. Omit entirely for guest checkouts. If you send it, include at least `id` or `email`.

  
    
      Shopify Customer ID. Used to look up the customer if `email` is not provided.
    

    
      Customer email address. Takes priority over `id` when both are provided; if no customer matches the email, `id` isn't tried.
    
  



  The line items in the cart. Must contain at least one item.

  
    
      The Shopify Product ID.
    

    
      The Shopify Variant/SKU ID.
    
  


### Example request: logged-in customer

```bash theme={null}
curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": {
      "id": "9049402769586",
      "email": "rahul.sharma@example.com"
    },
    "items": [
      {
        "product_id": "prod_1001",
        "variant_id": "var_1001_red_m"
      },
      {
        "product_id": "prod_2044",
        "variant_id": "var_2044_black_42"
      }
    ]
  }'
```

### Example request: guest checkout

```bash theme={null}
curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "product_id": "prod_1001",
        "variant_id": "var_1001_red_m"
      }
    ]
  }'
```

### Example response

```json 200 theme={null}
{
  "data": {
    "points_earned": 0,
    "message": "You will earn 0 points after completing this purchase"
  }
}
```

### Response fields


  
    
      The number of loyalty points the customer will earn after completing the purchase. Currently always `0` (see the warning above).
    

    
      A ready-to-display string. You can show this directly in your UI without additional formatting. The message is always returned, even when `points_earned` is `0`, so check `points_earned` before showing it.
    
  


### Display logic

```text theme={null}
If points_earned > 0:
  Show the message field directly in your UI

If points_earned === 0:
  Hide this section entirely — never show "You will earn 0 points"
```

***

## Endpoint 3: Redeem a reward (burn points)

This is the endpoint your checkout calls when a customer **actively chooses to spend their points** on a reward.

When the customer clicks "Redeem" on an available reward, call this endpoint. Yuko will:

1. Deduct the required points from the customer's balance
2. Generate a fresh Shopify discount code for that reward
3. Return the discount code so you can apply it to the order


  This endpoint is triggered by a **customer action** — not automatically at checkout load. Only call it when the customer explicitly clicks "Redeem" on a reward option.



  The request has no points amount, so only rewards with a fixed points cost can be redeemed here. A reward whose `reward_rule.method` is `increment` (customer chooses how many points to spend) always fails with `Insufficient points balance`, even when `can_redeem` is `true`. Hide the Redeem button for those rewards.


Full API reference → [`POST /customers/rewards/redeem`](/developer/api/redeem-reward)

Requires the `write:rewards` scope. Read-only keys can't redeem. See [Scopes](/developer/api/scopes).

### Request

```text theme={null}
POST https://api.yukoapp.com/api/v1/public/customers/rewards/redeem
```

### Required headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type` | `application/json` |

### Request body


  The Shopify Customer ID of the logged-in customer.



  The UUID of the reward the customer wants to redeem. Get this from the `rewards[].id` field in the Endpoint 1 response (`GET /customers/rewards/redeemable`).


### Example request

```bash theme={null}
curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9049402769586",
    "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5"
  }'
```


  The `reward_id` comes directly from the `rewards[].id` field in the Endpoint 1 response. Store these IDs when you render the rewards list so you have them ready when the customer clicks "Redeem".


### Example response

A `201 Created` status means the redemption was successful and a new coupon code has been generated.

```json 201 theme={null}
{
  "data": {
    "coupon_code": "YUKO-TVJ-BL1",
    "points_spent": 500,
    "reward_type": "fixed",
    "discount_value": 5,
    "expires_at": "2026-06-01T00:00:00+00:00"
  }
}
```

### Response fields


  
    
      The newly generated Shopify discount code (e.g. `YUKO-TVJ-BL1`). Apply this directly through your checkout's discount flow. `null` for `store_credit` reward types — the credit is added to the customer's account automatically.
    

    
      The number of points deducted from the customer's balance.
    

    
      The type of reward that was redeemed. One of `fixed`, `percentage`, `free_shipping`, `free_product`, `store_credit`.
    

    
      The discount amount or percentage associated with the coupon.

      * For `fixed`: this is the amount in the store's currency (e.g. `5` means 5 off)
      * For `percentage`: this is the percentage (e.g. `10` means 10% off)
      * For `free_product`: the free product's price, or `0` if it isn't known
      * `0` for `free_shipping` and `store_credit` reward types
    

    
      When the generated coupon expires. `null` if the reward has no expiry, and always `null` for `store_credit` rewards.
    
  


### Errors

| Code | Scenario | What to do |
| - | - | - |
| `422` | Customer doesn't have enough points (`redemption_failed`, `Insufficient points balance`) | This shouldn't happen if you used `can_redeem` from Endpoint 1 correctly. Show the customer a message: "You don't have enough points for this reward." |
| `422` | Reward not found or is inactive (`redemption_failed`, `Reward not found or inactive`) | The reward may have been deactivated by the merchant. Refresh the rewards list by calling Endpoint 1 again. |
| `422` | Customer is excluded from the loyalty program (`Customer banned`), or loyalty is turned off (`Loyalty not enabled`) (`redemption_failed`) | Hide the loyalty panel. |
| `422` | The discount or store credit couldn't be created on Shopify (`redemption_failed`, e.g. `Failed to generate platform coupon`) | Show a generic error and let the customer retry or continue without the reward. |
| `422` | `customer_id` or `reward_id` missing, or `reward_id` isn't a UUID (`validation_error`) | Fix the request body. |
| `404` | Customer not found | The `customer_id` is not in Yuko. |
| `401` | Invalid API key | Check the `Authorization` header. |

### Display logic after a successful redemption

```text theme={null}
On successful 201 response:

1. Show the customer their new discount code:
   "Your reward is ready! Code: {coupon_code}"

2. Auto-apply the discount code to the order if your checkout supports it

3. Update the displayed points balance:
   New balance = old points_balance - points_spent

4. Remove the redeemed reward from the "available rewards" list in your UI
```


  After a successful redemption, the customer's points balance has decreased. If you have the old balance cached, subtract `points_spent` from it to show the updated balance without making another API call.


***

## Full checkout flow


  
    * **Shopify Customer ID** — only if the customer is logged in (needed for Endpoint 1)
    * **Product IDs and Variant IDs** for every item in the cart (needed for Endpoint 2)
  

  
    | Customer state | Call Endpoint 1? | Call Endpoint 2? | Call Endpoint 3? |
    | - | - | - | - |
    | Logged in, Shopify Customer ID available | ✅ Yes | ✅ Yes — include `customer` field | ✅ Yes — when customer clicks "Redeem" |
    | Guest checkout | ❌ No — skip | ✅ Yes — omit `customer` field | ❌ No — guests can't redeem points |
  

  
    Do not wait for one to finish before starting the other. Running them in parallel keeps checkout fast.

    ```bash theme={null}
    # Call 1 — Only if the customer is logged in
    curl --request GET \
      --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    ```bash theme={null}
    # Call 2 — Always run this, for both logged-in and guest customers
    curl --request POST \
      --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      --header "Content-Type: application/json" \
      --data '{
        "customer": {
          "id": "9049402769586"
        },
        "items": [
          {
            "product_id": "prod_1001",
            "variant_id": "var_1001_red_m"
          }
        ]
      }'
    ```
  

  
    Combine both responses to display the loyalty section. This is only an example; adapt it to your UI.

    ```text theme={null}
    ┌──────────────────────────────────────────────┐
    │  🏆  Your Rewards                            │
    │                                              │
    │  Points Balance: 650 pts                     │
    │                                              │
    │  ✅  $5 off your next order                 │
    │      Costs 500 pts              [Redeem →]  │
    │                                              │
    │  🔒  10% off your next order                │
    │      Earn 350 more points to unlock          │
    │                                              │
    │  🎟️  You have an unused coupon              │
    │      YUKO-TVJ-BL1          [Apply to order] │
    │                                              │
    │  💰  You'll earn 120 points on this order!  │
    └──────────────────────────────────────────────┘
    ```
  

  
    When a customer clicks "Redeem" on an available reward, call Endpoint 3 with their `customer_id` and the `reward_id` of the reward they selected.

    ```bash theme={null}
    curl --request POST \
      --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      --header "Content-Type: application/json" \
      --data '{
        "customer_id": "9049402769586",
        "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5"
      }'
    ```

    On a `201` response:

    * Take the `coupon_code` from the response and apply it to the checkout order
    * Update the displayed points balance: `new_balance = old_balance - points_spent`
    * Remove the redeemed reward from the UI rewards list

    
      The `reward_id` is the `id` field from the `rewards[]` array in the Endpoint 1 response. You should store these IDs when you render the rewards list so they're ready when the customer clicks.
    
  


***

## Error handling


  The loyalty panel is an **enhancement** to checkout — it must never block or break the purchase. If any Yuko API call fails, hide the loyalty panel silently and let checkout continue.


Full list of error codes → [Errors reference](/developer/api/errors)

### HTTP status codes

| Code | Meaning | What to do |
| - | - | - |
| `200` | Success | Use the response data |
| `401` | Unauthorized — API key missing or incorrect | Check the `Authorization` header and key value |
| `403` | Forbidden — token missing the right scope (`insufficient_scope`) | Ask the merchant to create a key with `write:rewards` and `read:points` |
| `404` | Customer not found | The `customer_id` doesn't exist in Yuko — hide the panel silently |
| `422` | Validation error (`validation_error`) or failed redemption (`redemption_failed`) | Check the `message` field in the response |
| `429` | Rate limit exceeded | Wait 1 second and retry once — see [Rate Limits](#rate-limits) |
| `500` | Yuko internal error | Retry once. If it persists, hide the panel and let checkout continue. |

### Error response format

All error responses from Yuko return an `error` object with a `code` and a `message`:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Customer not found"
  }
}
```

### Recommended handling pattern

```text theme={null}
401 → Log the error. Hide the loyalty panel.
404 → Customer has no Yuko account yet (common for new customers). Hide silently.
429 → Wait 1 second. Retry the same request once.
5xx → Retry once after a short delay. If it fails again, hide the panel.
Any other error → Hide the loyalty panel. Never block checkout.
```

***

## Rate limits

See full details → [Rate Limits reference](/developer/api/rate-limits)

| Limit | Value |
| - | - |
| Requests per second (per API token) | 10 |
| Error when exceeded | HTTP `429 Too Many Requests` |
| Reset interval | 1 second |


  **Cache the rewards list.** The `rewards[]` catalogue changes infrequently — you can cache it for 5–15 minutes. The `points_balance` and `customer_rewards[]` are customer-specific and should be fetched fresh each checkout session.


* **Don't poll.** Call both endpoints once when the customer arrives at checkout.
* **Retry with a delay.** On a 429, wait 1 second and retry once. Never retry immediately.

***

## Security rules


  **These rules are not optional.** Violating them exposes the merchant's API key and puts their store at risk.


### Rule 1: Never expose the API key on the frontend

The key is a secret. It must only ever live on your backend server.

* ❌ Never put it in browser-side JavaScript
* ❌ Never put it in a mobile app binary
* ❌ Never commit it to a public code repository
* ✅ Make all Yuko API calls from your backend — pass only the results to your frontend

### Rule 2: Use HTTPS everywhere

Always send requests to the `https://` base URL so the API key is never sent unencrypted.

***

## Authentication setup options

Choose whichever approach fits your architecture.


  
    This is the simplest approach. No OAuth flow required.

    How it works:

    
      
        The merchant goes to **Shopify Admin → Apps → Yuko Loyalty → Integrations → REST API** and creates a **Custom Key** with `write:rewards` and `read:points`.
      

      
        The merchant copies the token and pastes it into your checkout platform's merchant settings.
      

      
        Your backend reads the token from your settings and includes it in every Yuko API request for that merchant.
      
    

    **Pros:** Fast to set up. No OAuth flow required.\
    **Cons:** The merchant must manually copy-paste the token. If they regenerate it, it needs to be updated on your side.
  

  
    This gives merchants a one-click **Connect Yuko** button inside your checkout dashboard — no manual copy-pasting.

    How it works:

    
      
        Add a "Connect Yuko" button in your merchant dashboard settings.
      

      
        When the merchant clicks it, redirect them to Yuko's OAuth authorization page.
      

      
        The merchant reviews and approves the connection inside Yuko.
      

      
        Yuko redirects back to your platform with an authorization code. Your backend exchanges this code for an access token.
      

      
        Store the token securely. Use it for all Yuko API calls for that merchant going forward.
      
    

    Integration can be initiated from either side:

    | Initiated by | Description |
    | - | - |
    | **Your checkout platform** | You add the "Connect to Yuko" button. The merchant clicks it from your dashboard. |
    | **Yuko** | Yuko lists your platform as an option. The merchant connects from inside their Yuko settings. |

    
      To get started with OAuth, contact the Yuko team to receive your OAuth client credentials (client ID and client secret) and configure your redirect URI → [Book a call](https://cal.com/rameshelamathi/yuko-demo)
    
  


***

## Testing


  
    Contact the Yuko team for a test key, or use a real merchant's key on a development Shopify store.
  

  
    ```bash theme={null}
    curl --request GET \
      --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    **Expected:** HTTP 200 with `data.points_balance` in the response body.\
    If you get HTTP 401, the API key is wrong — check for extra spaces or incorrect values.
  

  
    ```bash theme={null}
    curl --request GET \
      --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=REAL_CUSTOMER_ID" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    Verify:

    * `points_balance` returns a number
    * `rewards[]` is populated with the merchant's reward options
    * `can_redeem` correctly reflects the customer's balance
    * `customer_rewards[]` returns any existing coupons
  

  
    ```bash theme={null}
    curl --request POST \
      --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      --header "Content-Type: application/json" \
      --data '{
        "customer": {
          "id": "REAL_SHOPIFY_CUSTOMER_ID"
        },
        "items": [
          {
            "product_id": "REAL_PRODUCT_ID",
            "variant_id": "REAL_VARIANT_ID"
          }
        ]
      }'
    ```

    Verify: the request returns HTTP 200 with `points_earned` and `message`. `points_earned` is currently always `0` (see the warning in Endpoint 2).
  

  
    Use a `reward_id` from the Endpoint 1 response (choose one where `can_redeem === true`).

    ```bash theme={null}
    curl --request POST \
      --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      --header "Content-Type: application/json" \
      --data '{
        "customer_id": "REAL_SHOPIFY_CUSTOMER_ID",
        "reward_id": "REWARD_ID_FROM_ENDPOINT_1_RESPONSE"
      }'
    ```

    Verify:

    * Response is HTTP `201` (not 200)
    * `coupon_code` is returned and is a valid Shopify discount code
    * `points_spent` matches the `points_cost` of the reward you redeemed
    * `expires_at` is present (or `null` if the reward has no expiry or is store credit)
  

  
    ```bash theme={null}
    curl --request POST \
      --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
      --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      --header "Content-Type: application/json" \
      --data '{
        "items": [
          {
            "product_id": "REAL_PRODUCT_ID",
            "variant_id": "REAL_VARIANT_ID"
          }
        ]
      }'
    ```

    Verify: Returns HTTP 200 with no `customer` field in the request body.
  

  
    | Test | How to trigger | Expected result |
    | - | - | - |
    | Wrong API key | Use `Bearer wrong_key` | HTTP 401 |
    | Unknown customer | Use `customer_id=0000000` | HTTP 404 |
    | Missing items | Send `"items": []` | HTTP 422 |
    | Guest checkout | Omit `customer` entirely | HTTP 200 |
    | Redeem with insufficient points | Use a `reward_id` where `can_redeem === false` | HTTP 422 |
    | Redeem with invalid reward ID | Use a made-up UUID as `reward_id` | HTTP 422 |
  

  
    * Customer with 0 points — panel shows rewards, all greyed out
    * Customer with no prior redemptions — `customer_rewards[]` is an empty array — handle without crashing
    * Guest customer — Endpoint 1 and Endpoint 3 are not called; only show earn estimate from Endpoint 2
    * `points_earned === 0` — hide the earn message; do not show "0 points"
    * After a successful redemption — UI updates the balance and removes the redeemed reward from the list
  


***

## Go-live checklist

### Security

* API key stored as an environment variable — not hardcoded anywhere
* All Yuko API calls made from the backend server — not the browser
* HTTPS used for all requests

### API integration

* `GET /customers/rewards/redeemable` working and returning correct data
* `POST /points/estimate` working for both logged-in and guest customers
* `POST /customers/rewards/redeem` working — returns `201` with a valid `coupon_code`
* Endpoints 1 and 2 fire in parallel at checkout load — not sequentially
* Endpoint 3 is only called on an explicit customer "Redeem" click — not at page load
* If any call fails, checkout continues without breaking

### UI

* Points balance displayed clearly
* Redeemable rewards shown with a "Redeem" button for rewards where `can_redeem === true`
* Rewards with insufficient points shown as greyed-out with "X more points needed"
* Unused coupon codes from `customer_rewards[]` surfaced with an apply action
* Points earn estimate shown when `points_earned > 0`
* After a successful redemption: balance updates, redeemed reward is removed from list, new coupon code is surfaced or auto-applied
* No loyalty UI shown for guest checkouts
* Empty `customer_rewards[]` handled gracefully — no crash, no blank space

### Rate limiting

* Retry logic in place for HTTP 429 — wait 1 second, retry once
* No polling within a single checkout session

### Authentication

* Plan in place for token rotation if the merchant regenerates their API key

***

## API reference links


  
    Points balance, available rewards, and unused coupons for a customer.
  

  
    Burn a customer's points and generate a discount code.
  

  
    How many points a customer earns on a given cart.
  

  
    How Bearer Token authentication works in the Yuko API.
  

  
    Full list of HTTP error codes and what they mean.
  

  
    Request limits and how to handle 429 errors.
  


***

## Support


  
    For integration questions, OAuth setup, and onboarding support.
  

  
    Full Yuko API reference.
  



# VIP Tier Change Object
Source: https://docs.yuko.so/vip-tier-change-object

How VIP tier changes appear in a customer's activities in the Yuko REST API.

When a customer enters, moves up or down, or keeps a VIP tier, Yuko records it in the customer's activity log. These records are returned by [List customer activities](/developer/api/list-customer-activities) (`GET /public/customers/activities`, requires the `read:activities` scope) as [activities](/activity-object) with `source_type` set to `loyalty_tiers`. To get only tier changes, pass `source_type=loyalty_tiers`.

To read a customer's current tier instead of the history, use [Get customer tier](/developer/api/get-customer-tier).

## Properties


  Unique identifier for the tier change activity.



  Yuko's internal UUID for the customer whose tier changed.



  The kind of tier change. One of `vip_tier_entry` (the customer reached their first tier), `vip_tier_upgrade`, `vip_tier_downgrade`, `vip_tier_retained` (the customer kept their tier at re-evaluation).



  Always `loyalty_tiers` for tier changes.



  For tier changes, this is the customer's Yuko UUID.



  Always `null`; tier changes don't change the points balance.



  Always `0` for tier changes.



  Always `null` for tier changes.



  The tier details of the change.

  
    
      The tier the customer was in before the change. `null` when the customer had no tier (always for `vip_tier_entry`, and for a manual tier assignment to a customer with no tier).

      
        
          The tier's unique identifier.
        

        
          The tier's name. An empty string if the tier has since been deleted.
        
      
    

    
      The tier the customer is in after the change. `null` for a `vip_tier_downgrade` where the customer dropped out of all tiers.

      
        
          The tier's unique identifier.
        

        
          The tier's name.
        
      
    
  



  When the tier change was recorded (ISO 8601).



  ```json The VIP Tier Change object theme={null}
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
    "activity_type": "vip_tier_upgrade",
    "source_type": "loyalty_tiers",
    "source_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
    "entry_type": null,
    "points": 0,
    "earning_type": null,
    "metadata": {
      "previous_tier": {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Silver"
      },
      "current_tier": {
        "uuid": "7fb39c85-3a3f-4247-8333-2e05a9c8ae28",
        "name": "Gold"
      }
    },
    "created_at": "2025-12-17T12:36:33+00:00"
  }
  ```



# VIP Tiers
Source: https://docs.yuko.so/vip-tiers/overview

Reward your most valuable customers with tier levels, point multipliers, per-campaign bonuses and entry benefits.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → VIP


## Introduction

VIP Tiers add levels to your loyalty program, such as Bronze, Silver and Gold. Customers move into a tier when their points earned, amount spent or order count reaches the tier's threshold. Each tier can earn points faster and unlock benefits such as discounts, free shipping, free products, bonus points or store credit.

VIP is its own item in the Yuko sidebar, next to Loyalty and Referral.

## What problem this solves

A flat loyalty program rewards every customer the same way. Your best customers usually drive most of your revenue. Tiers recognise them and give everyone else a clear goal to work toward.

## When to use

* A small group of customers contributes a large share of revenue.
* You want a progression customers can climb, with a clear "you've made it" moment.
* You want top customers to earn faster on specific actions, such as orders or reviews.
* You want to give recurring perks, such as monthly store credit, to high-value customers.

## Overview

The VIP page has four sections:

* **VIP Tiers Status**: turns the VIP program on or off.
* **Tiers**: your tier list. Click **Add New Tier** to create a tier, or **Edit** to open one.
* **Tiers Calculation**: what qualifies a customer for a tier and over which period.
* **Advanced Program Settings**: the program start month and what happens when a period resets. Below it, **Reset VIP Tiers** recalculates every customer's tier.

Each tier has:

* A name, description and icon.
* A **Tier entry** threshold.
* A **Default point multiplier**, plus optional **Campaign rewards** that override it for specific Ways to Earn.
* **Entry benefits** that customers receive when they enter the tier.

New stores start with three tiers: **Bronze** (the default tier, 0 points, 1x), **Silver** (1,000 points, 2x) and **Gold** (5,000 points, 3x). The default qualification is **Total points earned** over a **Rolling year**. You can rename and change all of these.

## Before you start

Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).
The Yuko **Theme App Embed** is enabled in your active theme — see [Theme App Embed](/installation-and-setup/theme-app-embed).
Your loyalty program is enabled under **Loyalty Program Status** at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs**.
Your point labels are set in [Loyalty Settings](/loyalty/program-settings).

At least one [Way to Earn](/loyalty/ways-to-earn/overview) is active, so customers build up measurable activity.
You've decided whether tiers should reward spend, points or order frequency.

VIP Tiers are available on select plans. If your plan doesn't include them, the status toggle is disabled and shows an upgrade badge.

## Setup guide

### 1. Turn on VIP Tiers


  
    In your Shopify admin, go to **Apps → Yuko Loyalty → VIP**.
  

  
    Under **VIP Tiers Status**, switch the toggle on. The badge next to the page title changes to **Enabled**.
  


Turning VIP Tiers off asks for confirmation and disables all tier-related features.

### 2. Choose how customers qualify

Under **Tiers Calculation**, set **Qualification for tier is based on**:

| Option | Customers move up by… | Good for |
| - | - | - |
| **Total points earned** | Earning points from any Way to Earn | Rewarding engagement |
| **Total amount spent** | Spending more in your store | Growing revenue |
| **Order count** | Placing more orders | Growing purchase frequency |

Then set the **Qualification period type**:


  
    Customer progress accumulates forever from the program start date. Once achieved, tiers are permanent unless manually adjusted.
  

  
    Customer progress is tracked over a 12-month window. During the first program year, the window runs from your program start date to today. After the first anniversary, it becomes the trailing 12 months from today.
  

  
    Customer qualification progress restarts each calendar year on January 1. In the first program year, progress counts from your program start date.

    When Calendar year is selected, you can also tick **Include the last year**. This keeps earned tiers active through December 31 of the following calendar year, so a tier earned in 2026 is kept until the end of 2027.
  


Changing the qualification metric, the period type, **Include the last year**, the program start month or the reset option asks you to confirm. After you save, Yuko recalculates tiers for all customers, and some customers may move to a different tier.

### 3. Set the start month and reset behaviour


  
    Under **Advanced Program Settings**, pick a month and year. The program starts on the 1st day of that month. Activity before this date doesn't count toward tiers.
  

  
    Under **Tier Reset Options**, pick one:

    * **Reset After Period End**: automatically moves customers back to lower tiers when program periods reset, based on what they qualify for in the new period.
    * **No Tier After Reset**: removes customers from all tiers when periods reset, so they have to re-qualify.
  

  
    Click **Save** in the save bar at the top of the page.
  


### 4. Create or edit a tier


  
    Under **Tiers**, click **Add New Tier**, or click **Edit** on an existing tier.
  

  
    * **Tier name**: shown to customers on your storefront.
    * **Description**: optional text about the tier.
  

  
    Enter the points, amount or number of orders needed to enter this tier. The label matches your qualification metric. The default tier's threshold can't be changed.
  

  
    The multiplier applied to points earned by customers in this tier, for example `1.5` for 1.5x. Use **Campaign rewards** (next step) to override it for a specific Way to Earn.
  

  
    Under **Campaign rewards**, click **Add campaign reward** and fill in:

    * **Name**: shown on your storefront.
    * **Campaign**: the Way to Earn this reward applies to.
    * **Point multiplier**: multiplies the points this campaign awards. Between 1.1x and 10x.
    * **Bonus points**: adds a fixed number of points on top (a whole number, at least 1).

    Turn on at least one of the two options. Each Way to Earn can have only one campaign reward per tier. Campaigns without an entry keep the tier's default multiplier.
  

  
    Under **Entry benefits**, click **Add Benefits** and pick a benefit type. See [Tier benefits](#tier-benefits) below.
  

  
    Under **Customize tier icon**, keep **Default** or choose **Custom** and upload your own image (JPG, PNG, GIF or WEBP, under 1 MB).
  

  
    Click **Save**. The **Summary** card on the right lists the threshold, multiplier, benefits and campaign rewards.
  


After you save a tier, a read-only **Tier Identifier** appears under the name, for example `YUKO:TIER:…`. Copy it to reference the tier in integrations. Yuko adds this identifier as a Shopify customer tag to customers in the tier and creates a matching Shopify customer segment, so you can target tier members in Shopify and in your marketing tools.

### 5. Turn on tiers for your Ways to Earn

Tier multipliers and campaign rewards only apply to a Way to Earn when its **Tiers** toggle is on. Open the Way to Earn under **Loyalty → Programs** and check **Tiers**. The panel then lists the **Tier Multipliers** for each tier. The default campaigns created at install have Tiers turned on.

If a campaign reward points at a Way to Earn that was deleted, turned off or has Tiers turned off, the tier shows a warning and the reward isn't applied until you fix it.

## Tier benefits

Entry benefits are given to a customer when they enter the tier. The types are:

| Benefit | What the customer gets |
| - | - |
| **Amount discount** | A fixed amount off |
| **% off discount** | A percentage off (up to 50%) |
| **Free shipping** | Free shipping, with optional country restrictions and a maximum shipping price |
| **Free product** | A selected product for free |
| **Bonus points** | A one-off number of points (**Number of points**), with optional expiry |
| **Store credit** | Store credit: one time, recurring or as cashback (see below) |
| **Custom benefit** | A text-only perk shown to customers, such as "Early access to new products". Yuko doesn't apply it automatically. |

### Discount benefit options

Amount discount, % off discount, Free shipping and Free product benefits share these settings:

* **Method**: **Automatic** applies the discount at checkout without a code. **One-time code** (labelled **One-time discount code** on discount benefits) issues the customer a code and lets you set a **Coupon Prefix**.
* **Applies to**: All products, Specific collections or Specific products (amount and percentage discounts). Amount discounts can also be set to **Only apply discount once per order**.
* **Purchase type** (amount, percentage and free shipping benefits): One-time purchase, Subscription or Both. Subscription options only take effect if your store sells subscriptions.
* **Minimum purchase requirements**: none, a minimum purchase amount or a minimum quantity of items.
* **Combine with other discounts**: product and order discounts. Amount, percentage and free product benefits can also combine with free shipping.
* **Expiry Settings**: an optional expiry after a number of days, weeks, months or years.

### Store credit benefits

Each tier can have one store credit benefit. Pick a **Store Credit Type**:

* **One time**: a single store credit amount when the customer enters the tier.
* **Recurring**: credit issued on a schedule. Set the **Recurring Period** (weeks, months or years), the start day or date, the **Recurring Interval** (for example, every 2 months) and the **Maximum Times** it repeats.
* **% cashback after every purchase**: the customer earns a percentage of each purchase back as store credit (**Cashback %**).

You can add an expiry, and with **Enable Holdings** you can hold each credit for a set period (**Holding Value** and **Holding Period**) before the customer can use it.

## How it works

* **Evaluation.** Yuko evaluates a customer's tier when their points change (for points-based tiers) or when an order completes (for spend- and order-based tiers). It also re-checks tiers on a schedule, so period resets are applied.
* **Placement.** The customer is placed in the highest tier whose threshold they meet within the current qualification window.
* **Upgrades** apply straight away. Entry benefits for the new tier are issued, and the Shopify customer tag is updated.
* **Retention.** Once a customer enters a tier, they keep it until their retention window ends, even if their activity drops. The window ends:

  * **Lifetime**: never.
  * **Calendar year**: December 31 of the year they entered the tier, or December 31 of the following year with **Include the last year**.
  * **Rolling year**: 12 months after they entered the tier.

  When the window ends, the **Tier Reset Options** setting decides whether they move down to the tier they qualify for or lose their tier.
* **Admin changes skip retention.** Changing the qualification settings or using **Reset All Tiers** re-evaluates everyone under the new rules, regardless of retention. These recalculations don't send customer-facing workflow events.
* **Points.** The tier multiplier and campaign bonus points are added as a separate tier bonus entry in the customer's activity, alongside the base points. Multipliers apply when points are awarded, not retroactively.
* **Bulk updates.** While Yuko updates customer tags or metafields in bulk, a banner at the top of the VIP page shows the update is in progress, or that it failed.

### On your storefront

* The tier name, description, icon and benefits appear in [Floating Rewards](/onsite-widgets/floating-launcher), the [Rewards Landing Page](/onsite-widgets/rewards-landing-page) VIP block and the [Customer Account Page](/onsite-widgets/customer-account-page).
* **Free product** tier benefits are shown as product cards in Floating Rewards, [Cart Redeem](/onsite-widgets/cart-redeem) and [Loyalty Nudges](/onsite-widgets/loyalty-nudges).

### Notifications and automations

* The **Tier unlocked** email is sent when a customer reaches a new tier. Edit it under **Loyalty → Emails**. See [Loyalty emails](/emails/loyalty-emails).
* [Workflows](/workflows/triggers-and-conditions) have VIP triggers: VIP Tier Entry, Upgrade, Downgrade, Retained, Retention Warning, Milestone Nudge and Period Start. **VIP Tier Retention Warning** fires before a customer's retention window ends, so you can nudge them to keep their tier.
* [Shopify Flow](/integrations/shopify-flow) has VIP Tier Entry, Upgrade and Downgrade triggers.

### Assign a tier manually

You can override a customer's tier from **Customers**:


  
    Go to **Customers** and click the customer.
  

  
    In the **VIP tier** card, click **Assign tier**. Pick a **Tier**, optionally set **Expires at (optional)** and add a **Note (optional)** with the reason.
  

  
    The card now shows a **Manual** badge and when the override expires.
  


The expiry date sets both the override expiry and the retention expiry. Leave it empty for no expiry. Click **Clear override** to return the customer to automatic evaluation. See [Customers](/loyalty/customers).

### Reset all tiers

Under **Reset VIP Tiers**, click **Reset All Tiers** and confirm with **Reset Tiers**. Yuko recalculates every customer's tier from their current points or spend history and places them in the tier they qualify for now. This can't be undone.

### Limitations

* The default tier can't be deleted, and its threshold can't be changed. You can rename it.
* A Way to Earn can have only one campaign reward per tier.
* Each tier can have only one store credit benefit.
* Tier multipliers apply only to Ways to Earn with **Tiers** turned on. They don't apply to points you add manually.
* Multiplier booster campaigns can be set to **Ignore if customer earned VIP tier multiplier**. See [Booster campaigns](/loyalty/booster-campaigns/overview).

## Examples

* **Revenue-focused (Total amount spent, Lifetime):**
  * Bronze: \$0, 1x
  * Silver: \$400, 1.5x, 5% off discount (one-time code)
  * Gold: $1,000, 2x, free shipping (automatic) and $10 store credit every month
* **Engagement-focused (Total points earned, Rolling year):**
  * Bronze: 0 points, 1x
  * Silver: 1,000 points, 1.5x, plus a campaign reward of 3x on **Write a review**
  * Gold: 5,000 points, 2x, 5% cashback as store credit after every purchase
* **Frequency-focused (Order count, Calendar year with Include the last year):**
  * Bronze: 0 orders
  * Silver: 3 orders, 200 bonus points on entry
  * Gold: 8 orders, a free product and a +100 bonus points campaign reward on **Place an order**

## Best practices

**Keep it to 3–4 tiers.** More tiers make each one feel less special.
**Make higher tiers clearly better.** A 1.1x multiplier rarely changes behaviour; 2x usually does.
**Use campaign rewards to steer behaviour.** A bigger multiplier on reviews or social follows for top tiers rewards the actions you want most.
**Use the Tier Identifier segment** to send VIP-only campaigns from Shopify or your email tool.
**Set up a retention reminder.** A workflow on **VIP Tier Retention Warning** gives customers a reason to buy before they lose their tier.

## FAQs


  
    No. The default tier can't be deleted and its threshold is fixed. You can rename it and change its multiplier, benefits and icon.
  

  
    Usually, because the default tier has no threshold. A customer can show **No tier** in Customers, for example after a period reset with **No Tier After Reset**, until they're evaluated again.
  

  
    Yes. Yuko recalculates tiers, so some customers may move. Tell your customers about major changes so VIPs aren't surprised.
  

  
    A campaign reward replaces the tier's default multiplier for that Way to Earn and can also add fixed bonus points. Ways to Earn without a campaign reward use the default multiplier.
  

  
    Nothing until their retention window ends. Downgrades are skipped while the window is active. After it ends, the customer moves to the tier they qualify for, or loses their tier if you chose **No Tier After Reset**.
  

  
    Yes. Yuko adds the identifier as a tag to customers in the tier, removes it when they leave, and keeps a Shopify customer segment for the tier up to date.
  


## Related


  
    Configure how customers earn points across your store.
  

  
    Set up the rewards customers can redeem with their points.
  

  
    Run time-bound multipliers, bonuses and challenges on top of earning.
  

  
    Point labels, earning and revert statuses, exclusions and order tags.
  

  
    View balances and activity, adjust points and assign tiers.
  

  
    Reward your best customers with tier multipliers and benefits.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Action Nodes
Source: https://docs.yuko.so/workflows/action-nodes

The workflow steps that do something for the customer, Send Email, Coupon, Points Credit and Points Debit, with every setting explained.


  **Where to find this:** Inside any workflow, click the **+** on a connecting line → **Add Node** → **Actions**


## Introduction

Action nodes are the steps that actually do something when a customer reaches them. The **Add Node** dialog lists these actions:

| Node | What it does |
| - | - |
| [Send Email](#send-email) | *"An email will be sent to the contact when they reach this step."* |
| [Coupon](#coupon) | *"Generate a unique coupon code for the contact at this step."* |
| [Points Credit](#points-credit) | *"Credit loyalty points to the contact when they reach this step."* |
| [Points Debit](#points-debit) | *"Deduct loyalty points from the contact when they reach this step."* |
| [WhatsApp](/workflows/whatsapp-node) | Send a WhatsApp template through a connected provider |
| [Engati](/workflows/partner-nodes) / [kwikEngage](/workflows/partner-nodes) | Send a template message through Engati or Kwik Engage |

Timing and logic nodes (**Time Delay**, **If / Else**) are covered in [Time Delay & Exit](/workflows/wait-and-exit) and [Triggers & Conditions](/workflows/triggers-and-conditions).

Click any node on the canvas to open its settings panel. Save the panel to apply your changes.

## Send Email

Sends an email to the customer.


  
    Pick **Send Email** in **Add Node**. A new email node starts with the subject *New Email*.
  

  
    Click the node. The panel shows a preview of the email (switch between **Desktop view** and **Mobile view**). Click **Edit** to open the [Template Editor](/emails/template-editor).
  

  
    Set the subject, preview text, title, message, CTA and footer. Use [shortcodes](/emails/shortcodes). The **Available Template Variables** card lists the shortcodes for this workflow's trigger, plus the Redemption group. Click **Save**.
  


* The node card shows **Emails sent** so far.
* Emails use your sender settings from [Email Settings](/emails/sender-and-branding).
* The [Advanced Editor](/emails/template-editor#advanced-editor) is available on select plans.

## Coupon

Creates a unique Shopify discount code for the customer at this step. Show it in a later Send Email node with the **Coupon** block in the Advanced Editor.

| Setting | Options |
| - | - |
| **Node Identifier** | A random identifier for this node, with a copy button (*"Unique identifier for this coupon node."*). Email coupon blocks use it to find this coupon. |
| **Discount Type** | **Percentage (%)** (default, 10), **Amount** or **Free Shipping** |
| **Value** | The percentage or amount (not shown for Free Shipping) |
| **Set validity** | Toggle on and enter **Valid upto (in days)** to make the code expire |
| **Purchase type** | **One-time purchase**, **Subscription** or **Both** |
| **Minimum purchase requirements** | **No minimum requirements**, **Minimum purchase amount** or **Minimum quantity of items** |
| **Product Restrictions** | **Applies to**: **All products**, **Specific collections** or **Specific products**. For Amount discounts, **Only apply discount once per order**. |
| **Shipping Restrictions** (Free Shipping) | **All countries** or **Selected countries**, and **Exclude shipping rates over a certain amount** with a **Maximum shipping rate** |
| **Combinations** | Whether the code combines with **Product discounts**, **Order discounts** and **Shipping discounts** |

**Pair Coupon with Send Email.** Put the Coupon node first, then add the **Coupon** block in the email and pick this node's identifier, so the customer sees their code.

## Points Credit

Adds points to the customer's balance. Available on Shopify stores.

| Setting | What it does |
| - | - |
| **Method** | **Fixed amount of points**: the same number of points for everyone. **Incremental points**: points based on the order amount. You can only choose **Incremental points** when the workflow trigger is **Order Paid**. On every other trigger, Method is fixed to **Fixed amount of points**. |
| **Points to earn** | Fixed: the number of points to credit. Incremental: the points earned *for every* **Amount spent**. |
| **Amount spent** | Incremental only. For example, 1 point for every 10 spent gives 25 points on an order with a subtotal of 250. |
| **Credited reason** | *"Store why these points were credited for support and audit logs."* Shown in the customer's points history. |
| **Enable points expiry for this credit** | Expire these points after **Expire after** N **Days**, **Weeks**, **Months** or **Years**. |
| **Enable on-hold period before crediting points** | Hold the points as pending for **Hold points for** N **Days**, **Weeks**, **Months** or **Years** before they become available. |

**Incremental points** use the order subtotal, which is why they're only offered on the **Order Paid** trigger. If the order can't be found or its subtotal is zero, the step fails and the customer's run stops there.

Points credited by a workflow count as earned points. Without an on-hold period, they fire the **Earn Points** event right away, which also sends the built-in **Points earned** email if it's active.

## Points Debit

Removes points from the customer's balance. Available on Shopify stores.

| Setting | What it does |
| - | - |
| **Points to debit** | The number of points to remove |
| **Debited reason** | *"Store why this debit happened for support and audit logs."* |

If the customer doesn't have enough points, the step fails with *"Insufficient point balance"* and nothing is deducted. The customer doesn't continue to the next steps, and their subscriber status becomes **Failed**. You can see the reason in [Analytics](/workflows/analytics).

To avoid failed runs, put an **If / Else** with **Points Balance** *is at least* your debit amount before the Points Debit node (available on loyalty, VIP and booster triggers).

## Examples

**1. Welcome bonus.** Trigger **Joined Loyalty Program** → Points Credit (Fixed, 100, reason *Welcome bonus*) → Send Email.

**2. Downgrade win-back.** Trigger **VIP Tier Downgrade** → Coupon (Percentage, 15, valid 14 days) → Send Email with the Coupon block.

**3. Extra points on paid orders.** Trigger **Order Paid** → Points Credit (Incremental, 1 point for every 20 spent, hold for 14 days).

## Best practices

**Always fill in the reason.** Support teams rely on **Credited reason** and **Debited reason** to explain balance changes.
**Use the on-hold period for order-based credits.** It gives returns time to happen before the points can be spent.
**Give coupons a validity.** An expiry date creates urgency and keeps old codes from piling up.

## FAQs


  
    No. The Coupon node supports Percentage, Amount and Free Shipping discounts. Free-product rewards are available as a [way to redeem](/loyalty/ways-to-redeem/free-product).
  

  
    The node credits exactly the points you set (or the incremental calculation).
  

  
    A credit fires **Earn Points**. If your workflow's trigger is also Earn Points, use **No re-entry** or a **Has Not in This Flow** profile filter so customers don't loop through it again.
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Workflow Analytics
Source: https://docs.yuko.so/workflows/analytics

Follow every customer through a workflow on the Subscribers tab, see why a step failed, and track email delivery, opens and clicks on the Emails tab.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Workflows → (any workflow) → **Analytics**


## Introduction

Each workflow has its own **Analytics** page (*"Track subscribers and email performance for this workflow."*). It has two tabs:

* **Subscribers**: every customer who entered the workflow, their status, and a step-by-step timeline.
* **Emails**: every email the workflow's Send Email nodes sent, with delivery, open and click status.

Open it with the **Analytics** button at the top of the workflow editor.

## Subscribers tab

A **subscriber** is one customer's run through the workflow. If re-entry is allowed, the same customer can appear more than once.

**Metric cards:** **Completed**, **In Progress** and **Failed**. Click a card to filter the table to that status.

**Table columns:**

| Column | Shows |
| - | - |
| **Subscriber ID** | The ID of this run |
| **Email** | The customer's email |
| **Trigger Type** | The trigger that started the run |
| **Date Entered** | When the customer entered the workflow |
| **Status** | **Completed**, **In Progress** or **Failed** |
| **Timeline** | **View** opens the step-by-step timeline. **Hide** closes it. |

Search the table with **Search by email**, or filter it by **Status**.

### Timeline and failure reasons

Click **View** on a row to see each step the customer went through, with its **Step Name**, **Type**, **Status**, **Retries** and **Completed At** time. Use the refresh button in the timeline header to reload it.

When a step **failed**, an **"i"** icon appears next to its status. Hover over it to see the reason, for example:

* *"Customer phone number not found"* (WhatsApp, Engati or kwikEngage node)
* *"Insufficient point balance"* (Points Debit)
* *"Order not found"* (Points Credit set to Incremental when the order can't be found)
* A provider API error from a WhatsApp node

Some failures (WhatsApp and partner nodes) let the customer continue to the next step. Others, such as Points Credit and Points Debit failures, stop the run and mark the subscriber **Failed**.

## Emails tab

**Metric cards:** **Delivered**, **Opened**, **Clicked** and **Bounced**. Click a card to filter.

**Table columns:**

| Column | Shows |
| - | - |
| **Subscriber ID** | The run the email belongs to |
| **Customer** | The recipient |
| **Node Name** | Which Send Email node sent it |
| **Sent At** | Send time, or *Not sent* |
| **Status** | Delivery status |
| **Skipped** | **Yes** if the email wasn't sent. Hover the info icon for the reason. |
| **Opened** / **Clicked** | Whether the customer opened the email or clicked a link |

Search with **Search emails** or filter by **Status** (**Delivered**, **Clicked**, **Opened**, **Bounced**, **Skipped**).

## How to use it


  
    After you turn a workflow on, open **Analytics** and check that subscribers move from **In Progress** to **Completed**.
  

  
    Filter by **Failed**, click **View** on a row, and hover the **"i"** icon on the failed step.
  

  
    Fix the cause (connect a provider, add a balance check, change the trigger), then watch new subscribers.
  


## Best practices

**Check Failed weekly.** Most failures point to a setup issue, such as a disconnected WhatsApp provider or customers without phone numbers.
**Compare Opened and Clicked across nodes.** **Node Name** tells you which email in a multi-step workflow performs best.
**Look at Skipped reasons.** They explain emails that were triggered but never sent.

## FAQs


  
    They're usually waiting on a **Time Delay** node. Open their timeline to see the last completed step.
  

  
    Open the email from **Loyalty**, **Referral** or **Membership → Emails**. The editor shows **Stats** and a **View Details** link. See [Emails](/emails/overview#email-analytics).
  

  
    No. Use the subscriber statuses and timelines to see where customers stopped.
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Build your first workflow
Source: https://docs.yuko.so/workflows/build-your-first

A step-by-step tutorial that rewards customers who move up a VIP tier with bonus points and a congratulations email, then takes the workflow Live.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Workflows → **Create Workflow**


## Introduction

In this tutorial you'll build a **VIP upgrade bonus** workflow:

```
VIP Tier Upgrade  ──→  Points Credit (200 points)  ──→  Send Email  ──→  Exit
```

When a customer moves up to a higher [VIP tier](/vip-tiers/overview), they get 200 bonus points and an email congratulating them on the new tier. The built-in [Tier unlocked](/emails/loyalty-emails#tier-unlocked) email only covers a customer's first tier, so this workflow fills the gap for upgrades.

## Before you start

Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).
The Yuko **Theme App Embed** is enabled in your active theme — see [Theme App Embed](/installation-and-setup/theme-app-embed).
Your loyalty program is enabled under **Loyalty Program Status** at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs**.
Your point labels are set in [Loyalty Settings](/loyalty/program-settings).

VIP tiers are set up with at least two tiers. See [VIP Tiers](/vip-tiers/overview).
Your sender details are set in **Account → Email Settings**. See [Email Settings & Custom Domains](/emails/sender-and-branding).

## Setup guide


  
    Go to **Workflows** and click **Create Workflow** → **Create from Scratch**. The new workflow opens on the canvas as a **Draft**.
  

  
    Click the title at the top and rename it, for example *VIP upgrade bonus*.
  

  
    Click the **Trigger** node. In the trigger list (grouped by **Loyalty**, **VIP Tiers**, **Referral**, **Membership** and **Orders**), search for and select **VIP Tier Upgrade**.
  

  
    In the trigger panel under **Re-entry criteria**, choose **Allow re-entry**, so a customer who upgrades again later (Silver → Gold → Platinum) gets the bonus each time.
  

  
    Under **Trigger filters**, click **Add**, choose the **Current Tier Name** field and set it to, for example, *Gold*. Only upgrades into Gold will enter the workflow. Skip this step to reward every upgrade.
  

  
    Click the **+** on the line below the trigger. In **Add Node**, pick **Points Credit**. Set **Method** to **Fixed amount of points**, **Points to earn** to *200* and **Credited reason** to *VIP upgrade bonus*. Save the node.
  

  
    Click the **+** below Points Credit and pick **Send Email**. In the node panel, click **Edit** to open the [Template Editor](/emails/template-editor). Write a subject such as *Welcome to `{{ current_tier_name }}`, `{{ first_name }}`!* and a message that mentions the bonus and the new balance with `{{ points_balance }}`. Click **Save**, then go back to the workflow.
  

  
    Every path already ends in an **Exit** node (*"The automation will stop here."*). There's nothing to configure.
  

  
    In the Template Editor, click **Send Test Email** to see the email in your inbox with sample data.
  

  
    Changes save automatically (you'll see **Saved** at the top). Click **Turn on workflow**. The status changes from **Draft** to **Live**. Running workflows Live is available on select plans.
  


## How it works

1. A customer's tier is re-evaluated and they move to a higher tier. Yuko fires **VIP Tier Upgrade**.
2. If the customer passes your trigger filters and re-entry rule, they become a **subscriber** of the workflow.
3. **Points Credit** adds 200 points with the reason *VIP upgrade bonus*. You'll see it in the customer's activity on the [Customers](/loyalty/customers) page.
4. **Send Email** sends your email. Shortcodes like `{{ current_tier_name }}` are filled in for this customer.
5. The subscriber reaches **Exit** and is marked **Completed** in [Analytics](/workflows/analytics).

## Variations

* **Wait before emailing:** add a [Time Delay](/workflows/wait-and-exit) of 1 Day(s) before Send Email, with **Set a delay until a specific time of day** at 10:00.
* **WhatsApp instead of email:** swap Send Email for the [WhatsApp node](/workflows/whatsapp-node).
* **Different bonus per tier:** add an **If / Else** node after the trigger with **Current Tier Name** equals *Platinum*. Give the **Yes** path a bigger Points Credit.
* **Downgrade win-back:** build a second workflow on **VIP Tier Downgrade** with a [Coupon](/workflows/action-nodes#coupon) and a Send Email.

## Best practices

**Use a clear Credited reason.** It appears in the customer's points history, so support can see where the points came from.
**Mind the order.** Put Points Credit before Send Email so `{{ points_balance }}` already includes the bonus.
**Watch the first few subscribers.** Open **Analytics** after going Live and check that subscribers reach **Completed**.

## FAQs


  
    Pick the trigger carefully. Once a trigger is set, the trigger panel shows its filters and re-entry settings rather than the trigger list. To use a different trigger, create a new workflow.
  

  
    Running workflows Live is available on select plans. You can still build and save workflows as Draft.
  

  
    Yes. Points credited by a workflow count as earned points, so the built-in **Points earned** email (if active) also sends. Turn it off, or rely on it instead of a separate Send Email node.
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Workflows
Source: https://docs.yuko.so/workflows/overview

Build visual automations that react to loyalty, VIP, referral, membership and order events by sending emails and WhatsApp messages, issuing coupons and adjusting points.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Workflows


## Introduction

Workflows are automations you build on a visual canvas. Each workflow starts with one **trigger** (an event such as *Earn Points*, *VIP Tier Upgrade* or *Order Delivered*), then runs the steps you add: wait, branch with **If / Else**, send an email or WhatsApp message, create a coupon, or credit or debit points.

Use workflows when the [built-in emails](/emails/overview) aren't enough, for example to send a WhatsApp message when a customer reaches a new tier, wait three days before a follow-up, or treat VIP customers differently from everyone else.

## How a workflow fits together

```
Trigger  ──→  Time Delay  ──→  If / Else ──Yes──→  Send Email  ──→  Exit
                                   │
                                   └──No───→  WhatsApp  ──→  Exit
```

* **Trigger:** the event that starts the workflow, plus optional trigger and profile filters and re-entry rules. See [Triggers & Conditions](/workflows/triggers-and-conditions).
* **Actions:** **Send Email**, **Coupon**, **Points Credit**, **Points Debit**, **WhatsApp**, **Engati** and **kwikEngage**. See [Action Nodes](/workflows/action-nodes), the [WhatsApp node](/workflows/whatsapp-node) and [Partner Nodes](/workflows/partner-nodes).
* **Timing:** **Time Delay**. See [Time Delay & Exit](/workflows/wait-and-exit).
* **Logic:** **If / Else** splits customers into a **Yes** and a **No** path.
* **Exit:** every path ends in an Exit node that Yuko adds for you.

Each customer who enters a workflow is a **subscriber**. You can follow every subscriber's path in [Analytics](/workflows/analytics).

## The Workflows list

* **Create Workflow** → **Create from Scratch** opens a new, blank workflow.
* Tabs: **All**, **Live** and **Draft**, plus an **Event Type** filter and search.
* Columns: **Title**, **Trigger Type**, **Subscribers** and **Status** (**Live** or **Draft**).
* Select several workflows to set them Live, set them to Draft, or delete them in bulk.

New workflows start as **Draft**. Changes on the canvas save automatically. When you're ready, click **Turn on workflow** to make it **Live**. Running workflows Live is available on select plans.

The workflow editor needs a desktop-sized screen. On a phone, Yuko shows *"Workflow editor requires desktop view"*.

## Workflows and built-in emails

The emails under **Loyalty → Emails**, **Referral → Emails** and **Membership → Emails** run on the same engine, but you manage them from those tabs, not from the Workflows list. If you build a workflow on the same trigger as a built-in email, turn the built-in email off so customers don't get two messages.

## Before you start

Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).
The Yuko **Theme App Embed** is enabled in your active theme — see [Theme App Embed](/installation-and-setup/theme-app-embed).
Your loyalty program is enabled under **Loyalty Program Status** at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs**.
Your point labels are set in [Loyalty Settings](/loyalty/program-settings).

## Get started


  
    [Build your first workflow](/workflows/build-your-first) walks through a complete example.
  

  
    See the full list in [Triggers & Conditions](/workflows/triggers-and-conditions).
  

  
    Choose from [Action Nodes](/workflows/action-nodes) and the [WhatsApp node](/workflows/whatsapp-node).
  

  
    Turn the workflow on, then watch subscribers and emails in [Analytics](/workflows/analytics).
  


## Best practices

**Start small.** A trigger, one action and an exit is a complete workflow. Add branches once the basics work.
**Set re-entry deliberately.** Decide whether a customer should go through the workflow once, every time, or at most once per period.
**Check Analytics after launch.** Failed steps show the reason, so you can fix setup issues early.

## FAQs


  
    Not today. New workflows start from scratch with **Create from Scratch**.
  

  
    A Draft workflow stops accepting new subscribers. Customers who are already in it, for example waiting on a Time Delay, carry on through their remaining steps. Check [Analytics](/workflows/analytics) for subscribers still marked **In Progress**.
  

  
    Not from the workflow builder. For outbound data, see [Integrations](/integrations/overview).
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Partner Nodes
Source: https://docs.yuko.so/workflows/partner-nodes

The standalone Engati and kwikEngage workflow nodes, and why the WhatsApp node, which supports 13 providers, is usually the better choice.


  **Where to find this:** Inside any workflow, click the **+** on a connecting line → **Add Node** → **Actions** → **Engati** or **kwikEngage**


## Introduction

Before the unified [WhatsApp node](/workflows/whatsapp-node) existed, Yuko had two standalone partner nodes: **Engati** and **kwikEngage**. Each sends a template message to the customer's phone number through that partner. They still appear in the **Add Node** picker on Shopify stores, and existing workflows that use them keep working.

**For new workflows, use the [WhatsApp node](/workflows/whatsapp-node).** It supports Engati and Kwik Engage as providers, plus 11 others (AISensy, Zoko, WATI, DelightChat, QuickReply.ai, Interakt, BiteSpeed, BotSpace, AskEva, [Whamaa](/integrations/whamaa) and [ConvertWay](/integrations/convertway)), with a provider picker that shows connection status and the same shortcodes as your trigger.

## Before you start

Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).
The Yuko **Theme App Embed** is enabled in your active theme — see [Theme App Embed](/installation-and-setup/theme-app-embed).
Your loyalty program is enabled under **Loyalty Program Status** at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs**.
Your point labels are set in [Loyalty Settings](/loyalty/program-settings).

The partner is connected under **Integrations**: [Engati](/integrations/engati) or [Kwik Engage](/integrations/kwik-engage). The node uses that connection's credentials to send.

## Engati node

*"Send an Engati message to the contact when they reach this step."*

| Setting | What to enter |
| - | - |
| **Namespace** | Your Engati namespace, a unique identifier such as `550e8400-e29b-41d4-a716-446655440000` |
| **Endpoint URL** | The Engati API endpoint URL |
| **Template Name** | The template identifier (no spaces) |
| **Parameters** | One value per template variable, in order. Use plain text or shortcodes. |

## kwikEngage node

*"Send a kwikEngage message to the contact when they reach this step."*

| Setting | What to enter |
| - | - |
| **Endpoint URL** | The Kwik Engage API endpoint URL |
| **Template Name** | The template identifier (no spaces) |
| **Language Code** | The template language, for example `en_US` or `hi_IN` |
| **Parameter Count** | How many variables the template has |
| **Parameters** | One value per template variable, in order |

## How partner nodes work

1. The customer reaches the node.
2. Yuko takes the phone number from the customer's record. Without one, the step fails with *"Customer phone number not found"*.
3. Yuko calls the partner's API with your template and parameters.
4. The step is marked completed or failed, and the workflow continues to the next node either way. It doesn't wait for the customer to reply.

## Best practices

**Migrate when convenient.** Rebuilding a partner node as a WhatsApp node (choosing Engati or Kwik Engage as the provider) gives you the connection badge and trigger-aware shortcodes.
**Don't send the same template through two nodes.** Using a partner node and a WhatsApp node for the same message sends it twice.

## FAQs


  
    Check that the partner is still connected under **Integrations** and that the customer has a phone number. The failure reason is shown in the subscriber timeline in [Analytics](/workflows/analytics).
  

  
    Use the [WhatsApp node](/workflows/whatsapp-node), which covers 13 providers.
  


## Related


  
    One node for all 13 WhatsApp providers.
  

  
    Choosing and connecting a WhatsApp provider.
  



  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Triggers & Conditions
Source: https://docs.yuko.so/workflows/triggers-and-conditions

Every event that can start a Yuko workflow, the trigger and profile filters that narrow who enters, re-entry rules, and If / Else branching.


  **Where to find this:** Shopify admin → Apps → Yuko Loyalty → Workflows → (any workflow) → click the **Trigger** node


## Introduction

Every workflow starts with one **trigger**, the event that puts a customer into the workflow. On the trigger node you can also:

* add **trigger filters** (conditions on the event's data) and **profile filters** (conditions on the customer),
* choose a **re-entry** rule.

Inside the workflow, an **If / Else** node splits customers into a **Yes** and a **No** path using the same kinds of conditions.

## Triggers

The trigger list is grouped into **Loyalty**, **VIP Tiers**, **Referral**, **Membership** and **Orders**, and you can search it. A trigger only appears when its module is turned on. For example, booster triggers need Booster Campaigns, and membership triggers need Memberships.

### Loyalty

| Trigger | Fires when |
| - | - |
| **Earn Points** | A customer earns points (including points credited by a workflow) |
| **Redeem Points** | A customer redeems points for a reward |
| **Points Adjusted** | Points are adjusted manually, for example from the Customers page |
| **Points Expiring Reminder** | A customer's points are about to expire |
| **Points Expired** | A customer's points expire |
| **Reward Expiry Reminder** | A redeemed reward is about to expire |
| **Reward Expired** | A redeemed reward has expired |
| **Joined Loyalty Program** | A customer joins the loyalty program |
| **Birthday Reminder** | A customer's birthday is coming up |
| **Customer Birthday** | On the customer's birthday |
| **Anniversary Reminder** | A customer's anniversary is coming up |
| **Customer Anniversary** | On the customer's anniversary |
| **One-time Campaign Points Awarded** | A customer receives points from a [One-time Campaign](/loyalty/one-time-campaigns) that has **Trigger workflow events** turned on |
| **Benefit Unlocked** | A tier, booster or membership benefit is executed for a customer (including each recurring execution) |
| **Booster Campaign Entered** | A customer takes their first qualifying action in a [booster campaign](/loyalty/booster-campaigns/overview) |
| **Booster Campaign Progression** | A customer's progress toward a booster goal advances (streak step, milestone, spending goal) |
| **Booster Campaign Rewarded** | A customer completes a booster campaign and its rewards are issued (fires once, even with several rewards) |

### VIP Tiers

| Trigger | Fires when |
| - | - |
| **VIP Tier Entry** | A customer qualifies for a VIP tier for the first time |
| **VIP Tier Upgrade** | A customer qualifies for a higher tier |
| **VIP Tier Downgrade** | A customer's tier is downgraded after retention expires |
| **VIP Tier Retained** | A customer re-qualifies before their retention window expires |
| **VIP Tier Retention Warning** | A customer's retention window expires in about 30 days |
| **VIP Milestone Nudge** | A customer passes a progress milestone (25%, 50%, 75%, 90%) toward the next tier |
| **VIP Period Start** | A new qualifying period begins (the calendar year rolls over or the rolling window shifts) |

### Referral

| Trigger | Fires when |
| - | - |
| **Referrer welcome** | A customer joins the referral program as a referrer |
| **Friend reward unlocked** | A referred friend claims their friend reward |
| **Referrer Rewarded** | A referrer is rewarded for a successful referral |
| **Referral Completed** | A referral is completed |

### Membership

| Trigger | Fires when |
| - | - |
| **Membership Subscribed** | A customer subscribes to a membership for the first time |
| **Membership Upgraded** | A subscription changes to a higher-priced plan |
| **Membership Downgraded** | A subscription changes to a lower-priced plan |
| **Membership Paused** | A subscription is paused |
| **Membership Reactivated** | A paused or cancelled membership is activated again |
| **Membership Cancelled** | A subscription is cancelled |

### Orders

| Trigger | Fires when |
| - | - |
| **Order Paid** | A Shopify order is paid |
| **Order Delivered** | A Shopify order is marked delivered |

## Trigger filters

After you pick a trigger, click **Add** under **Trigger filters** to only let in events that match. Conditions are grouped, and you choose whether groups and conditions combine with **AND** or **OR**. Each condition has a **Field**, an **Operator** (such as *equals*, *contains*, *is greater than*) and a **Value**.

The fields depend on the trigger:

| Fields | Triggers |
| - | - |
| **Email**, **First name**, **Last name**, **Phone number** | Every trigger except Benefit Unlocked |
| **City**, **Country Code** | Order, loyalty, VIP, booster and membership triggers |
| **Points Balance**, **Total Earned Points** | Loyalty, VIP and booster triggers |
| **Point Source** | Earn Points, Redeem Points, Points Expired, Points Adjusted, One-time Campaign Points Awarded |
| **Days Before** | Points Expiring Reminder, Reward Expiry Reminder, Birthday Reminder, Anniversary Reminder, VIP Tier Retention Warning |
| **Campaign Identifier**, **Campaign Name** | One-time Campaign Points Awarded |
| **Current Tier Name** | VIP triggers |
| **Previous Tier Name** | VIP Tier Upgrade, VIP Tier Downgrade |
| **Tier Progress %** | VIP Tier Entry, Upgrade, Downgrade, Retained, Retention Warning, Milestone Nudge, Period Start |
| **Milestone %** | VIP Milestone Nudge |
| **Booster Campaign Name**, **Booster Campaign Type**, **Booster Completed Actions**, **Booster Campaign Progress %** | Booster triggers |
| **Benefit Module**, **Benefit Type** | Benefit Unlocked |
| **Membership Name**, **Subscription Status** | Membership triggers |
| **Referral Link** | Referral triggers and several loyalty triggers |
| **Category**, **Collection**, **Product Name**, **Product ID**, **Variant ID**, **Order Status**, **Order Financial Status**, **Order Fulfillment Status**, **Currency**, **Language**, **Province Code**, **Order Count** | Order Paid, Order Delivered (**Currency**, **Product Name** and **Province Code** are also available on Earn Points) |

### One-time campaign conditions

To run a workflow for one specific [One-time Campaign](/loyalty/one-time-campaigns):

1. In the campaign, turn on **Trigger workflow events** and copy its read-only **Identifier**.
2. In the workflow, use the **One-time Campaign Points Awarded** trigger.
3. Add a trigger filter **Campaign Identifier** *equals* the identifier you copied. Or use **Campaign Name** to match on the name.

The identifier never changes, so it's safer than the name if you might rename the campaign.

## Profile filters

Click **Add** under **Profile filters** to filter on the customer rather than the event. Choose a **Condition type**:

| Condition type | What it checks |
| - | - |
| **User Action** | Whether the person has performed an action, with a count and a **Time frame** |
| **Properties About Someone** | A property of the customer, such as email or name |
| **IN or NOT in the EU** | **Is** / **Is Not** in a **Region** (**European Union** or **United States**) |
| **Receive Marketing** | Whether the customer accepts marketing (**Yes** / **No**) |
| **Has Not in This Flow** | The customer hasn't been in this workflow **At Any Time**, or **In The Last** N Hours, Days, Months or Years |

## Re-entry criteria

Under **Re-entry criteria** on the trigger node, set whether a customer can go through the workflow more than once:

| Option | Behaviour |
| - | - |
| **No re-entry** | *"Profiles will only enter once, even if trigger conditions are met again."* |
| **Allow re-entry** | *"Profiles will re-enter whenever trigger conditions are met."* |
| **Allow re-entry after a time period** | Re-enter only after a **Time period** you set in hours, days or weeks has passed |

## If / Else

Add **If / Else** from the **Logic** group in **Add Node**: *"Profiles are split into two paths based on whether they meet the condition."* Customers who match take the **Yes** path. Everyone else takes the **No** path.

The If / Else panel has two sections:

* **Source-Based Filters**: conditions on the trigger's data, with the same fields as the trigger filters above.
* **Profile Filters**: the same condition types as the trigger's profile filters.

Each path continues to its own actions and ends in its own **Exit**.

## Examples

**1. Thank-you for a specific campaign.** Trigger **One-time Campaign Points Awarded** → filter **Campaign Identifier** equals your Diwali campaign → Send Email *"Your festive bonus is here"*.

**2. Tiered birthday message.** Trigger **Customer Birthday** → If / Else **Points Balance** *is greater than* 1000 → Yes: WhatsApp message, No: Send Email.

**3. Retention nudge.** Trigger **VIP Tier Retention Warning** → Send Email reminding the customer how to keep their tier.

## Best practices

**Filter at the trigger when you can.** Customers who don't match never enter, which keeps Analytics clean. Use If / Else when both groups need something.
**Use Has Not in This Flow** to stop customers from getting the same message too often, even with re-entry allowed.
**Turn off the matching built-in email.** If you build a workflow on Earn Points or Birthday Reminder, turn off the built-in email for that event to avoid duplicates.

## FAQs


  
    Triggers only appear when their module is active. Turn on Memberships or Booster Campaigns first.
  

  
    No. For win-back flows, use **VIP Tier Retention Warning**, **VIP Tier Downgrade** or **Points Expiring Reminder**.
  

  
    No. Use **Order Paid** or **Order Delivered**.
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# Time Delay & Exit
Source: https://docs.yuko.so/workflows/wait-and-exit

Pause a workflow for minutes, hours or days, optionally until a time of day or chosen weekdays, and understand how every path ends at an Exit node.


  **Where to find this:** Inside any workflow, click the **+** on a connecting line → **Add Node** → **Timing** → **Time Delay**


## Time Delay

A **Time Delay** node holds each customer for a set time before they move on to the next step. In the picker it's described as: *"The workflow will wait for this duration before moving to the next step."*

### Settings

| Setting | What it does |
| - | - |
| **Duration** | How long to wait. Must be at least 1. |
| **Unit** | **Minute(s)**, **Hour(s)** or **Day(s)** |
| **Set a delay until a specific time of day** | After the duration, wait until a set **Time** in a chosen **Time Zone**. Only available with **Day(s)**. |
| **Set a delay until chosen day(s) of the week** | After the duration, wait until one of the weekdays you select. Pick at least one day. Only available with **Day(s)**. |

### Setup


  
    Click the **+** where you want the pause, then choose **Time Delay**.
  

  
    Enter a **Duration** and pick the **Unit**, for example *3* **Day(s)**.
  

  
    With **Day(s)** selected, turn on **Set a delay until a specific time of day** and choose the **Time** and **Time Zone**. You can also turn on **Set a delay until chosen day(s) of the week** and select the days.
  

  
    Save the panel. The node on the canvas shows the delay.
  


### When to use

* **Space out messages:** Send Email → Time Delay 3 Day(s) → WhatsApp.
* **Give a coupon time to work:** Coupon → Send Email → Time Delay 5 Day(s) → reminder email.
* **Send at a friendly hour:** Time Delay 1 Day(s) until 10:00 in your store's time zone.

## Exit

Every path in a workflow ends at an **Exit** node: *"The automation will stop here."* Yuko adds Exit nodes for you, including one at the end of each **If / Else** branch. There's nothing to configure.

When a customer reaches Exit, their subscriber status in [Analytics](/workflows/analytics) becomes **Completed**.

## How it works

1. A customer reaches the Time Delay node and their status stays **In Progress**.
2. Yuko waits for the duration, then, if set, until the next matching time of day or weekday.
3. The customer moves to the next node.
4. At the end of the path they reach Exit and are marked **Completed**.

## Best practices

**Avoid back-to-back messages.** Put a Time Delay between two sends on different channels, so customers don't get an email and a WhatsApp in the same minute.
**Use a time of day for multi-day delays.** "1 Day(s) until 10:00" lands in inboxes in the morning instead of whenever the trigger happened.
**Remember re-entry.** If re-entry is allowed, a customer can be in the workflow more than once at the same time, each waiting separately.

## FAQs


  
    No. Use **Day(s)** (for example 14 days for two weeks). There's no option to wait until a calendar date.
  

  
    **Set a delay until a specific time of day** and the weekday option only work when the unit is **Day(s)**.
  

  
    No. Exit has no settings. It simply ends the path.
  

  
    Yes. Add an **If / Else** node after the Time Delay. See [Triggers & Conditions](/workflows/triggers-and-conditions).
  


## Related


  
    A step-by-step example from blank canvas to a Live workflow.
  

  
    Events that start a workflow, filters, re-entry and If / Else.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  

  
    Pause a workflow and end it cleanly.
  

  
    Send WhatsApp templates through any of 13 providers.
  

  
    Subscribers, timelines, failures and email performance.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.
  



# WhatsApp Workflow Node
Source: https://docs.yuko.so/workflows/whatsapp-node

Send an approved WhatsApp template at any step of a workflow through any of 13 connected WhatsApp providers, with shortcodes for personalisation.


  **Where to find this:** Inside any workflow, click the **+** on a connecting line → **Add Node** → **Actions** → **WhatsApp**


## Introduction

The WhatsApp node sends one WhatsApp template message to the customer when the workflow reaches it. It uses a WhatsApp provider you've connected under **Integrations**, and fills the template's parameters with [shortcodes](/emails/shortcodes) such as `{{first_name}}` or `{{points_balance}}`.

## Supported providers

The node supports **13** providers:

| Provider | Integration guide |
| - | - |
| AISensy | [AISensy](/integrations/aisensy) |
| Zoko | [Zoko](/integrations/zoko) |
| WATI | [WATI](/integrations/wati) |
| DelightChat | [DelightChat](/integrations/delightchat) |
| Kwik Engage | [Kwik Engage](/integrations/kwik-engage) |
| Engati | [Engati](/integrations/engati) |
| QuickReply.ai | [QuickReply.ai](/integrations/quickreply-ai) |
| Interakt | [Interakt](/integrations/interakt) |
| BiteSpeed | [BiteSpeed](/integrations/bitespeed) |
| BotSpace | [BotSpace](/integrations/botspace) |
| AskEva | [AskEva](/integrations/askeva) |
| Whamaa | [Whamaa](/integrations/whamaa) |
| ConvertWay | [ConvertWay](/integrations/convertway) |

## Before you start

Yuko app is installed on your Shopify store — see [Install Yuko on Shopify](/installation-and-setup/install-on-shopify).
The Yuko **Theme App Embed** is enabled in your active theme — see [Theme App Embed](/installation-and-setup/theme-app-embed).
Your loyalty program is enabled under **Loyalty Program Status** at **Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs**.
Your point labels are set in [Loyalty Settings](/loyalty/program-settings).

At least one WhatsApp provider is connected under **Integrations**. See the [WhatsApp overview](/integrations/whatsapp).
The template you want to send is **approved** in your provider's dashboard, and you know its name or ID.

## Setup guide


  
    Click the **+** where the message should go and choose **WhatsApp**.
  

  
    The panel shows every provider as a card with a **Connected** or **Disconnected** badge. Disconnected providers can't be selected. Click the provider you want to use.
  

  
    Enter the fields your provider needs (see the table below), for example **Template Name** and **Language Code**.
  

  
    Set the parameter count to match your template, then fill each parameter in order. Type plain text or insert a shortcode, for example `{{first_name}}` for the first variable and `{{points_balance}}` for the second.
  

  
    Save the node. If a field is missing, the panel shows what to fix.
  


### Provider fields

| Provider | Fields |
| - | - |
| AISensy | Endpoint URL, Campaign Name, Source, Tags, Attributes, Template Parameter Count |
| Zoko | Message Type (**Template**, **Rich Template (with media header)**, **Button Template (with interactive buttons)**), Template ID, Template Language, Template Argument Count |
| WATI | Template Name, Broadcast Name, Channel Number, Client ID, Parameter Count |
| DelightChat | Automation ID, Message Data Count, CTA Button Text, CTA Button URL |
| Kwik Engage | Endpoint URL, Template Name, Language Code, Parameter Count, Add CTA Button / CTA Button Count |
| Engati | Namespace, Endpoint URL, Template Name, Parameter Count |
| QuickReply.ai | Template ID, Parameter Count, Media URL (Optional), Button Parameters (Optional) |
| Interakt | Template Name, Language Code, Template Parameter Count, Callback Data, Add CTA Button / CTA Button Count |
| BiteSpeed | Template ID, Channel ID, Params Count, Add CTA Button / CTA URL |
| BotSpace | Template ID, Channel ID, Template Parameter Count |
| AskEva | Template Name, Language Code, Parameter Count, Add CTA Button / CTA Button Count |
| Whamaa | Template Name, Language Code, Parameter Count, Add CTA Button / CTA Button Count |
| ConvertWay | Template Name, Language Code, Parameter Count, Add CTA Button / CTA Button Count |

## Shortcodes

The shortcode picker in each parameter field lists the shortcodes for your workflow's **trigger**, the same set a Send Email node gets, plus `{{redemption_link}}`. For example, a **VIP Tier Upgrade** workflow offers `{{current_tier_name}}`, while a **Redeem Points** workflow offers `{{reward_code}}`. See the [Shortcodes Reference](/emails/shortcodes) for what each one means.

## How it works

1. A customer reaches the WhatsApp node.
2. Yuko uses the phone number on the customer's record. If there's no phone number, the step is marked **failed** with *"Customer phone number not found"* and the workflow moves on.
3. Yuko fills the template parameters with the customer's data and sends the template through the provider's API.
4. The step is marked **completed**, or **failed** with the provider's error. Either way, the workflow continues to the next node.

You can see each step's result and failure reason in [Analytics](/workflows/analytics).

### Limitations

* One template per node. To send a second message, add another WhatsApp node, ideally after a Time Delay.
* Templates must be created and approved in your provider's dashboard. Yuko sends them but doesn't edit their wording.
* Delivery, read and reply status stay in your provider's dashboard. Yuko tracks completed or failed.
* The provider must be included in your plan. Otherwise the step fails with a message asking you to upgrade.

## Examples

**1. Tier upgrade celebration.** **VIP Tier Upgrade** → WhatsApp: *"Welcome to `{{current_tier_name}}`, `{{first_name}}`! Your balance is `{{points_balance}}` points."*

**2. Points expiry nudge.** **Points Expiring Reminder** → WhatsApp: *"`{{first_name}}`, `{{expiring_points}}` points expire in `{{days_until_expiry}}` days."*

**3. One-time campaign announcement.** **One-time Campaign Points Awarded** with a **Campaign Identifier** filter → WhatsApp: *"We've added bonus points to your account. Redeem here: `{{redemption_link}}`"*.

**4. Friend reward.** **Friend reward unlocked** → WhatsApp with `{{discount_code}}`.

## Best practices

**Get templates approved first.** Unapproved templates fail at send time.
**Back up with email.** WhatsApp fails when there's no phone number. Use an **If / Else** on **Phone number** to send an email to customers without one.
**Space out messages.** Put a **Time Delay** between an email and a WhatsApp so they don't arrive in the same minute.
**Test with your own customer record.** Make sure it has a phone number, and trigger the event yourself before going Live.

## FAQs


  
    It shows **Disconnected**. Connect it under **Integrations** (see the provider's guide above), then reopen the node.
  

  
    The step fails with *"Customer phone number not found"* and the workflow continues to the next node.
  

  
    No. The wording is fixed in the approved template in your provider's dashboard. Yuko only fills the parameters.
  

  
    Use the WhatsApp node. It supports Engati and Kwik Engage as providers, plus 11 others. See [Partner Nodes](/workflows/partner-nodes).
  


## Related


  
    Choosing and connecting a WhatsApp provider.
  

  
    Send Email, Coupon, Points Credit and Points Debit.
  



  
    India / SEA — cost-effective high-volume Business API.
  

  
    Shopify-native — fast onboarding, plain / rich / button templates.
  

  
    Global — named-parameter templates, team inbox.
  

  
    Multi-channel — WhatsApp + Instagram + email, automation-driven sends with CTA.
  

  
    India-leaning — templates with optional dynamic-URL CTA buttons.
  

  
    Conversational AI — namespace-scoped templates.
  

  
    AI-first — media headers, dynamic CTA buttons (requires Client ID + Secret Key).
  

  
    India — template messages with CTA URL buttons and callback metadata.
  

  
    Shopify-focused — named parameters and optional CTA URLs with shortcodes.
  

  
    Multi-channel WhatsApp automation — lightweight setup, positional parameters.
  

  
    SEA / MENA — templates with dynamic URL-suffix CTA buttons.
  

  
    Template messages with language codes and up to 2 dynamic CTA URL buttons.
  

  
    WhatsApp marketing platform — templates with up to 2 dynamic CTA URL buttons.
  



  
    Talk to our team for personalised setup help.

    **Time:** 30 minutes
  

  
    Visit our support hub for help articles, live chat and ticket submission.
  

  
    Documentation across loyalty, referrals, memberships and more.
  

  
    Add Yuko to your Shopify store from the Shopify App Store.