> For the complete documentation index, see [llms.txt](https://native-app-co.gitbook.io/stork-credit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://native-app-co.gitbook.io/stork-credit/automations/referral-codes.md).

# Referral codes

Give influencers and partners their own codes, let shoppers enter them in your cart, at checkout or on the Thank you page, and reward everyone who uses one with store credit.

Referral codes let a shopper enter a code, such as an influencer's code, in your cart, at checkout, or on the Thank you page after they order. They're tagged with that code, and an order-value automation rewards them with store credit.

It works for **guest checkouts** as well as logged-in customers.

New to referrals? Follow the step-by-step guide in [Setting up referrals](/stork-credit/getting-started/setting-up-referrals.md).

{% hint style="info" %}
**Works on every Shopify plan.** Shoppers can enter codes in the **Referral Code** theme block (your cart page, or anywhere else in your theme) and in the **Referral Code** block on the **Thank you page**. Stores on **Shopify Plus** can also add the **Referral Code** block to checkout. See step 3 of [Setting up](#setting-up) below.
{% endhint %}

{% hint style="info" %}
Referral codes are available on the **Grow** and **Pro** plans. On Free, the **Referral codes** page is shown greyed out and can't be changed, under a notice naming those plans with a **See plans** button. See [Plans & billing](/stork-credit/reference/plans-and-billing.md).
{% endhint %}

## How it works

1. **In your cart or at checkout**, the shopper enters a code in a **Referral Code** block. If the code is active, they see your success message. The code is saved on their order, and nothing is added to their customer record yet.
2. **When the order is placed**, Stork Credit tags the order's customer with the code, for example `referral:SUMMER25`. For a guest, that's the customer Shopify matched or created from the email they entered.
3. **When the order is paid**, your referral reward rule sees the tag and credits the customer.

Because nothing is tagged until an order exists, entering a code and then abandoning the cart or checkout earns nothing.

### On the Thank you page

The order already exists when the shopper sees the Thank you page, so a code entered there works slightly differently:

1. **The shopper enters a code** in the **Referral Code** block on the Thank you page. If the code is active, Stork Credit tags the order's customer with it straight away.
2. **If the order is already paid**, which is usual for card payments, Stork Credit runs your referral reward rules again for that order. The shopper is credited for the order they just placed. They don't have to wait for their next order.
3. **If the order isn't paid yet**, for example with bank transfer or cash on delivery, the reward is issued when the order is paid, as for any other order.
4. **The block shows what the order earned**, for example *You've earned $5.00 in store credit on this order*. For an unpaid order it shows what the shopper will earn once it's paid.

A code entered on the Thank you page can't be removed. It must be entered within **24 hours** of the order being placed. After that, the block no longer accepts codes.

## Setting up

### 1. Create your codes

Go to **Referral codes** in the app and fill in:

| Field               | What it does                                                                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Code**            | What shoppers type in the Referral Code block. Not case-sensitive: `summer25` and `SUMMER25` are the same code. It 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's tag is shown in the list, for example `referral:SUMMER25`. Use **Edit** to change a code's label or success message later, and **Disable** to stop a code being accepted without deleting it.

{% hint style="info" %}
The success message is shown exactly as you type it, whatever language your store or checkout is displayed in.
{% endhint %}

### 2. Create a reward rule

A code on its own doesn't issue credit. The reward comes from an [order-value automation](/stork-credit/automations/order-value-automations.md) limited to customers with the code's tag. The quickest way to create one:

* **Create reward rule** next to a code creates a rule for that code only, for example to give one influencer's audience a bigger reward.
* **Create reward rule for all codes** creates one rule matching every tag that starts with `referral:`.

Either button opens a new order-value rule that's already filled in:

* **Eligibility:** Customers with specific tags, set to the code's tag.
* **Uses per customer:** Once per customer.

Enter the reward amount, adjust anything else, save, and **activate** the rule. You can also start from the **Referral Reward** [template](/stork-credit/automations/templates.md).

### 3. Add somewhere to enter codes

There are three places to add a Referral Code block. Use any of them, or all of them.

| Block                                  | Where it goes                                   | Shopify plan      |
| -------------------------------------- | ----------------------------------------------- | ----------------- |
| **Referral Code** theme block          | Your cart page, or any other page in your theme | Any plan          |
| **Referral Code** Thank you page block | The Thank you page shoppers see after ordering  | Any plan          |
| **Referral Code** checkout block       | Your checkout                                   | Shopify Plus only |

The **Referral codes** page has shortcuts for the theme and checkout blocks. Under **Add the Referral Code block**, **Add to theme** opens the theme editor with the block already added to your cart page, and **Add to checkout** opens the checkout editor. **Add to checkout** only appears on stores on Shopify Plus.

**Theme block:** click **Add to theme**, then **Save**. To add it by hand, go to **Online Store → Themes → Customize**, open your **Cart** page (or any other page), then **Add block → Apps → Referral Code**, and **Save**. You can change its heading, button text and messages, and its colours, in the block's settings.

**Thank you page block:** **Settings → Checkout → Customize**, choose **Thank you** from the page menu at the top, then **Add app block → Referral Code**, and **Save**.

**Checkout block:** click **Add to checkout**, or go to **Settings → Checkout → Customize**. Then **Add app block → Referral Code**. Place it where shoppers will see it, then **Save**.

A code applied with the theme block stays on the cart. So if you use both blocks, a shopper who applied a code in the cart sees it already applied in checkout, and can remove it there.

For more on both blocks, see [Cart & checkout widgets](/stork-credit/integrations/storefront-and-checkout.md#referral-code-blocks).

If you also use the **Automatic Store Credit** checkout block, it updates as soon as a code is applied or removed, so the shopper sees the credit their code earns before they pay. See [Cart & checkout widgets](/stork-credit/integrations/storefront-and-checkout.md#referral-codes-and-the-checkout-widget).

## What shoppers see

* **Code accepted:** your success message, the code, and a **Remove** link to take it off or switch to another code before paying.
* **Code accepted on the Thank you page:** your success message and the store credit the order earned, or will earn once it's paid. If the order doesn't qualify for a reward, the shopper sees the code instead. If a code was already entered in the cart or at checkout, the block shows that code instead of the field.
* **Thank you page, more than 24 hours after ordering:** *This code can no longer be applied*.
* **Unknown or disabled code:** *Invalid referral code*.
* **Logged-in customer who already used a code:** *Referral code already applied*. Their account keeps its first code.

## Rules worth knowing

* **First code wins.** A customer keeps the first referral tag they receive. A guest whose email belongs to a customer who already used a code keeps that original code, and the new one is ignored.
* **Every customer can use a code**, not only new customers. Pair the reward rule with **Once per customer** so each customer is rewarded once.
* **A code disabled before the order is placed** isn't applied, even if the shopper entered it while it was active.
* **Guests** receive the credit on the customer record matching their email. They sign in with that email to spend it, and Shopify's store credit notification tells them it's there.
* **Accelerated checkout** buttons that skip the checkout page, and draft order invoices, don't show the Referral Code checkout block, so no code can be entered there. Draft order invoices never carry a code.
* **Removing the tag** from a customer doesn't take back credit already issued.
* **Promotion stacking applies on the Thank you page too.** If stacking is off and another automation already credited the order when it was paid, a code entered on the Thank you page tags the customer but doesn't add a second reward to that order. See [Promotion stacking](/stork-credit/automations/promotion-stacking.md).
* **The order confirmation email** has already been sent by the time a shopper uses the Thank you page, so credit earned there doesn't appear in it. Shopify's store credit notification still tells the customer about it.

## Languages

The Referral Code block on the Thank you page is translated into English, French, German, Spanish, Italian, Dutch and Brazilian Portuguese, including its messages about earned credit. It follows the language the shopper sees your checkout in, and other languages show in English. The checkout block's field and button labels are translated into the same languages.

Your **success message** is always shown exactly as you typed it, whatever the shopper's language.

## Troubleshooting

Open the reward rule's **Runs** tab to see why an order was or wasn't credited. Runs started by a code entered on the Thank you page are marked *Referral code entered on the Thank you page*. See [Run history](/stork-credit/automations/run-history.md). The most common reasons:

| Reason                                                           | What to check                                                                                                                                                                                                               |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Customer doesn't have a matching tag*                           | The order has no **Referral code** under **Additional details**, or the rule's tag doesn't match the code. Codes entered on the Thank you page don't appear under **Additional details**. Check the customer's tags instead |
| *Customer already rewarded by this rule (once per customer)*     | The customer was rewarded on an earlier order                                                                                                                                                                               |
| *No customer on order*                                           | Shopify didn't attach a customer to the order, so there was no one to credit                                                                                                                                                |
| *Best-value only: another promotion already credited this order* | Promotion stacking is off, and another automation credited the order before the code was entered on the Thank you page                                                                                                      |
| *Already credited or held for this order*                        | The rule already credited this order, or is holding its credit. Nothing extra is issued                                                                                                                                     |