Setting up referrals

Set up a referral program in three parts: create referral codes, add an automatic reward rule, and add a Referral Code block to your cart, checkout or Thank you page.

Referrals take three parts: a code, an automatic reward rule and a Referral Code block. It works like this:

1. A shopper enters a code in your cart, at checkout, or on the Thank you page after ordering.

2. Stork Credit tags the customer with that code, for example referral:SUMMER25. This happens once the order is placed, or straight away on the Thank you page.

3. Your reward rule sees the tag and issues store credit for the order. For a code entered on the Thank you page after the order is already paid, the rule runs again so the order is still rewarded.

This works for guest checkouts as well as logged-in customers.

Referral codes are available on paid Stork Credit plans. On the Free plan, the Referral Code blocks in your cart and checkout reject every code, and the Thank you page block is hidden. See Plans & billing.

Part 1: Set up referral codes

Create one code for each influencer or partner.

1. Open Stork Credit and click Referral codes in the app menu.

2. Under New code, fill in the fields below.

3. Click Create code.

Field	What it does
Code	What shoppers type in the Referral Code block, for example SUMMER25. It isn't case-sensitive and can't be changed later
Label	Optional. A note for you, such as the influencer's name
Success message	Shown in the Referral Code block when the code is accepted. Defaults to Code Successfully Applied

Each code gets a customer tag, shown in Your codes, for example referral:SUMMER25. The reward rule in Part 2 looks for this tag.

• Edit changes a code's label or success message.

• Disable stops the code being accepted without deleting it.

• Delete removes the code permanently.

Part 2: Create the automatic reward

A code on its own issues nothing. The reward comes from an order-value automation that only applies to customers carrying the code's tag. The reward is store credit on the customer's account, not a discount at checkout.

On the Referral codes page, pick one of two shortcuts:

Button	Where	Use it to
Create reward rule	Next to a code	Reward one code differently, for example a bigger reward for one influencer's audience
Create reward rule for all codes	Beside Your codes	Use one rule for every code, matching any tag that starts with referral:

Either button opens a new order-value rule with these settings already filled in:

• Customer eligibility: Customers with specific tags, set to the code's tag.

• Uses per customer: Once per customer.

• Credit type: Fixed amount.

Then finish the rule:

1. Enter the reward Amount, or switch Credit type to a percentage of the order.

2. Set anything else you need, such as a minimum order value or an expiry for the credit.

3. Save the rule, then activate it.

An inactive rule credits nobody. Make sure the rule is active before you share your codes.

You can also start from the Referral reward template under Automations.

Part 3: Add the Referral Code block

Shoppers need somewhere to enter a code. There are three places to add a Referral Code block. Use any of them, or all of them:

• Theme block: for your cart page or anywhere else in your theme. Works on every Shopify plan.

• Thank you page block: for the page shoppers see after ordering. Works on every Shopify plan.

• Checkout block: for your checkout. Needs a store on Shopify Plus.

The quickest way to add the theme and checkout blocks is from the app. On the Referral codes page, under Add the Referral Code block, click Add to theme or Add to checkout. Each button opens the right Shopify editor in a new tab. Add to checkout only appears on stores on Shopify Plus.

In your cart (any Shopify plan)

1. On the Referral codes page, click Add to theme. The theme editor opens on your Cart page with the Referral Code block already added.

2. Optional: drag the block to where you want it, and change the heading, button text, messages and colours in the block's settings.

3. Click Save.

To add the block to a different page, or to add it by hand:

1. In Shopify admin, go to Online Store → Themes and click Customize.

2. Open your Cart page, or whichever page you want it on.

3. Click Add block → Apps → Referral Code.

4. Click Save.

Adding it with HTML and Liquid instead

If you can't add the block in the theme editor, paste the code below into your theme instead. This helps if:

• Apps doesn't appear under Add block on your cart page. This is common on older themes.

• You want the code field in a cart drawer or pop-up cart.

• You want to match your theme's design exactly.

The code works the same way as the block. It checks the code with Stork Credit, shows your success message, and saves the code on the cart so it reaches the order.

On a newer theme? Try Custom Liquid first. In the theme editor, open your Cart page and click Add section → Custom Liquid, or Add block → Custom Liquid if your theme offers it. Paste the code below into the Liquid code box and click Save. You don't need to edit any theme files.

To add it to your theme files:

1. In Shopify admin, go to Online Store → Themes. Click ⋯ → Duplicate to make a backup first.

2. On your live theme, click ⋯ → Edit code.

3. Under Snippets, click Add a new snippet. Name it stork-referral and click Done.

4. Paste the code below into the new snippet and click Save.

5. Open the file for your cart and paste this line where the code field should appear:

   {%- render 'stork-referral' -%}

   File names vary by theme. On Dawn and other Shopify themes, the cart page is sections/main-cart-footer.liquid and the cart drawer is snippets/cart-drawer.liquid.

6. Click Save, then check your cart on the live store.

{%- assign stork_referral = cart.attributes['Referral code'] -%}

<div class="stork-referral" data-stork-referral>
  <p class="stork-referral__heading">Have a referral code?</p>

  <div class="stork-referral__form"{%- if stork_referral != blank %} hidden{%- endif %}>
    <input
      type="text"
      class="stork-referral__input"
      placeholder="Referral code"
      aria-label="Referral code"
      autocomplete="off"
      autocapitalize="characters"
      spellcheck="false"
    >
    <button type="button" class="stork-referral__apply">Apply</button>
  </div>

  <div class="stork-referral__message" role="status" aria-live="polite">
    {%- if stork_referral != blank -%}
      Referral code applied: <strong>{{ stork_referral | escape }}</strong>
      <button type="button" class="stork-referral__remove">Remove</button>
    {%- endif -%}
  </div>
</div>

<style>
  .stork-referral { margin: 16px 0; }
  .stork-referral__heading { margin: 0 0 8px; font-weight: 600; }
  .stork-referral__form { display: flex; gap: 8px; }
  .stork-referral__form[hidden] { display: none; }
  .stork-referral__input { flex: 1; min-width: 0; padding: 10px 12px; }
  .stork-referral__message:not(:empty) { margin-top: 8px; }
  .stork-referral__remove { background: none; border: 0; padding: 0; text-decoration: underline; cursor: pointer; }
</style>

<script>
  (function () {
    // Runs once per page, even if the snippet appears more than once.
    if (window.storkReferralLoaded) return;
    window.storkReferralLoaded = true;

    const cartUpdateUrl = ((window.Shopify && Shopify.routes && Shopify.routes.root) || '/') + 'cart/update.js';

    // Saves the code on the cart. It must be called "Referral code" to reach the order.
    async function saveCode(value) {
      const response = await fetch(cartUpdateUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ attributes: { 'Referral code': value } })
      });
      if (!response.ok) throw new Error('Cart update failed');
    }

    function showMessage(root, text, code) {
      const message = root.querySelector('.stork-referral__message');
      message.replaceChildren(text);
      if (!code) return;

      const strong = document.createElement('strong');
      strong.textContent = code;
      const remove = document.createElement('button');
      remove.type = 'button';
      remove.className = 'stork-referral__remove';
      remove.textContent = 'Remove';
      message.append(' ', strong, ' ', remove);
    }

    async function applyCode(root) {
      const form = root.querySelector('.stork-referral__form');
      const input = root.querySelector('.stork-referral__input');
      const button = root.querySelector('.stork-referral__apply');
      const code = input.value.trim();
      if (!code) return;

      button.disabled = true;
      showMessage(root, '');

      try {
        // Stork Credit checks the code is real and active.
        const response = await fetch('/apps/stork-credit/proxy/referral', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ code: code })
        });
        const data = await response.json();

        if (!data.success) {
          showMessage(root, data.error || 'Invalid referral code');
        } else if (!data.applied) {
          showMessage(root, 'A referral code has already been applied to your account.');
        } else {
          await saveCode(data.code);
          form.hidden = true;
          showMessage(root, data.message || 'Referral code applied:', data.code);
        }
      } catch (error) {
        showMessage(root, "We couldn't apply that referral code. Please try again.");
      } finally {
        button.disabled = false;
      }
    }

    async function removeCode(root) {
      try {
        await saveCode('');
      } catch (error) {
        return;
      }
      root.querySelector('.stork-referral__input').value = '';
      root.querySelector('.stork-referral__form').hidden = false;
      showMessage(root, '');
    }

    document.addEventListener('click', function (event) {
      const root = event.target.closest('[data-stork-referral]');
      if (!root) return;
      if (event.target.closest('.stork-referral__apply')) applyCode(root);
      if (event.target.closest('.stork-referral__remove')) removeCode(root);
    });

    // Pressing Enter applies the code instead of submitting the cart.
    document.addEventListener('keydown', function (event) {
      if (event.key !== 'Enter' || !event.target.matches('.stork-referral__input')) return;
      event.preventDefault();
      applyCode(event.target.closest('[data-stork-referral]'));
    });
  })();
</script>

To change the wording, edit the text in the code. That includes the heading, the placeholder, the button labels and the messages. The success message comes from the code's own Success message in Stork Credit. The code field inherits your theme's fonts and button styles. You can restyle it with the stork-referral classes in the <style> section.

Leave two parts of the code as they are. 'Referral code' is the name the code is saved under, and Stork Credit looks for that exact name on the order. /apps/stork-credit/proxy/referral is where the code is checked. If either one changes, codes won't reach your orders and no one is credited.

Some cart drawers load their contents after the page has opened, so the code's script never starts. If Apply does nothing in your drawer, cut everything from <script> to </script> out of the snippet. Paste it into layout/theme.liquid, just above </body>. If it still doesn't work, get in touch and we'll help you place it.

Theme updates can replace edited files. After you update your theme, check the code field is still in your cart.

On the Thank you page (any Shopify plan)

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

2. From the page menu at the top of the editor, choose Thank you.

3. Click Add app block and choose Referral Code.

4. Place it where shoppers will see it, for example near the top of the page.

5. Click Save.

The block asks Have a referral code? and shows a code field with an Apply button. When a code is accepted, shoppers see your success message and the store credit their order earned. If the order isn't paid yet, they see what they'll earn once it is. Codes can be entered for 24 hours after the order is placed, and can't be removed once applied.

In your checkout (Shopify Plus)

1. On the Referral codes page, click Add to checkout. You can also get there from Shopify admin: go to Settings → Checkout and click Customize.

2. Click Add app block and choose Referral Code.

3. Place it where shoppers will see it, for example near the order summary.

4. Optional: add the Automatic Store Credit block the same way.

5. Click Save.

Block	What shoppers see
Referral Code	A code field and an Apply button. When the code is accepted, they see your success message, the code and a Remove link
Automatic Store Credit	The store credit this order will earn. It updates as soon as a code is applied or removed, so shoppers see their reward before paying

The Referral Code checkout block doesn't appear in accelerated checkouts that skip the checkout page, or on draft order invoices. No code can be entered there.

A code accepted in the cart or checkout block is saved on the order, and shows under Additional details on the order as Referral code. A code entered on the Thank you page is added to the customer's tags instead, because the order has already been placed.

For more on the blocks, see Cart & checkout widgets.

Test it

Place a test order with a code. The customer is tagged after the order is placed, not when the code is applied.

• The code is accepted in the Referral Code block and shows your success message

• The order shows Referral code under Additional details

• The customer has the referral: tag for the code once the order is placed

• Once the order is paid, the reward rule's Runs tab shows the credit issued

If something's missing, check these:

What you see	What to check
Invalid referral code	The code exists, is active, and your store is on a paid plan
Referral code already applied	The customer already has a referral tag. The first code wins
No Referral code on the order	A Referral Code block was added and saved in the theme editor or checkout editor. The checkout block needs Shopify Plus. Codes entered on the Thank you page never appear on the order. Check the customer's tags instead
Code on the order but no tag	The code was disabled before the order was placed, or the order has no customer
Tag but no credit	The rule is active and its tag matches. Check the reason in the rule's Runs tab. See Run history

For how codes behave in detail, such as guests, first-code-wins and removing tags, see Referral codes.