> ## Documentation Index
> Fetch the complete documentation index at: https://docs.referbro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Campaign Management
> Creating and configuring referral campaigns
The Campaign is the core of your referral program. It defines what incentives you offer, how rewards work, and what customers see in the referral widgets.
## Creating a Campaign
Navigate to **Apps → Referbro → Campaigns** in your Shopify Admin. From there:
1. Click **Create Campaign** to open **Campaign Configuration**.
2. Save your campaign details.
3. Return to the campaigns list to manage activation/deactivation and edit any campaign.
For a visual walkthrough of this flow, open [How To Create A Referral Campaign In Shopify](https://scribehow.com/viewer/How_To_Create_A_Referral_Campaign_In_Shopify__SpKkaCjkQZaZEJDK6TO87w).
Referbro supports multiple campaigns per store, but only one campaign can be active at a time. If another campaign is already active, a newly created campaign is saved as inactive.
### Discount Strategies
Choose how the **friend** (referee) receives their discount:
| Strategy | How It Works | Best For |
| :--------------- | :------------------------------------------------ | :----------------------------------------- |
| **Fixed Amount** | A flat currency discount (e.g., ₹150 off) | Consistent margins, lower-AOV stores |
| **Percentage** | A percentage of the cart subtotal (e.g., 10% off) | High-AOV stores, encouraging larger orders |
### Campaign Fields Reference
#### Incentive Configuration
| Field | Type | Description |
| :------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **Campaign Name** | Text | Internal name for your reference (customers don't see this) |
| **Discount Strategy** | Select | `Fixed Amount` or `Percentage` |
| **Discount Amount / Percentage** | Number | The discount value for the friend |
| **Minimum Subtotal** | Currency | Minimum cart value required for the discount to apply. Set to `0` for no minimum |
| **Referrer Reward** | Number | Amount or percentage the referrer earns per successful referral. For Percentage Discount Code, enter the percent (e.g., `15` for 15%) |
| **Referrer Reward Type** | Select | How the referrer is rewarded: `Cashback`, `Store Credit`, `Gift Card`, `Flat Amount Discount Code`, or `Percentage Discount Code` |
| **Reward Return Period (Days)** | Number | Days to wait after the friend's order delivery before issuing the referrer's reward. Use this to account for return/refund windows |
| **Store Credit Expiry (Days)** | Number | *(Only for Store Credit)* Number of days before issued store credit expires. Leave blank for no expiry |
| **Active Status** | Toggle | Pause or resume this campaign at any time (also manageable from the Campaigns list) |
#### Advanced Options
| Field | Description |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allow Without Code** | If enabled, rewards are issued even when a friend doesn't apply the discount code at checkout — as long as the referral source was tracked via the link click |
| **Combines With Order Discounts** | Whether this referral discount can stack with other order-level discounts |
| **Combines With Product Discounts** | Whether this referral discount can stack with product-level discounts |
| **Combines With Shipping Discounts** | Whether this referral discount can stack with shipping discounts |
### Widget Configuration
These fields control the text and behavior of the Refer & Earn widget that appears on your storefront:
| Field | What It Controls | Example |
| :------------------------------ | :-------------------------------------------------------------- | :--------------------------------- |
| **Share Message** | The default text pre-filled when a customer shares via WhatsApp | `Refer a friend and get ₹150 off!` |
| **First Line** | Main headline in the widget (the offer) | `₹150 off for your friends` |
| **Second Line** | Sub-headline (the reward) | `₹150 in your pocket` |
| **Third Line** | Optional tagline or additional CTA | *(e.g., "Share now!")* |
| **Button Label** | Text on the share/CTA button | `Share & Earn` |
| **Show Referral Code on UI** | Whether to display the raw referral code in the widget | Toggle on/off |
| **Auto-Generate for Logged In** | Automatically generate a referral code for logged-in customers | Toggle on/off |
After saving the widget text, use the [Refer & Earn widget Scribe](https://scribehow.com/viewer/How_to_Configure_Refer_and_Earn_Widgets_in_Shopify__GxG4UYOETyqp12igzNa-dA) to enable the widgets in Shopify.
#### UTM-Based Display
You can configure the widget to appear only for visitors who arrive via specific UTM parameters:
| Field | Description |
| :----------------- | :------------------------------------------------------------- |
| **Show on UTM** | Enable to restrict widget visibility to UTM-tagged traffic |
| **UTM Parameters** | Key-value pairs that must match (e.g., `utm_source: referral`) |
### Advanced Settings
These settings are hidden behind a disclosure toggle on the Campaign Configuration page (collapsed by default). **Only configure these if your Shopify order status does not update reliably.** In most cases, Shopify's native fulfillment and cancellation signals handle everything automatically.
| Field | Description |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Delivered Tag** | A Shopify order tag that indicates an order has been delivered. When this tag is applied to an order, Referbro treats it as delivered and schedules the referrer's reward (respecting the configured return period). Use only when Shopify's `fulfillment.shipment_status` is not being updated by your shipping provider. |
| **RTO Tag** | A Shopify order tag that indicates a Return-To-Origin (RTO). When this tag is applied to a referral order, Referbro cancels the pending reward. This is a DB-only cancellation — if a reward has already been issued (status `SUCCESS`), it will **not** be clawed back. |
Leave both fields empty unless you have confirmed that your Shopify order fulfillment status is unreliable. Configuring these incorrectly can lead to rewards being scheduled or cancelled prematurely.
**How RTO cancellation works:**
1. When the `orders/updated` webhook fires, Referbro checks if the configured RTO tag is present in the order's tags.
2. If the RTO tag is found **and** the order has an associated referral (i.e., a `DiscountInfo` record exists), the referral reward is set to `CANCELLED`.
3. If no referral record exists for the order, the RTO tag is silently ignored.
4. The RTO check runs **before** the delivery flow, so an RTO order that lacks a delivery date is still correctly handled.
***
## Discount Codes
When a campaign is active, Referbro automatically manages discount codes on Shopify:
* **For Referrers**: Each customer gets a unique referral code (e.g., `JOHN-AB12`). This code is linked to a Shopify discount that gives the friend the configured discount.
* **For Friends**: When a friend clicks a referral link and reaches your store, the discount is applied (or available to apply) at checkout.
Updating campaign settings (e.g., changing the discount amount) applies to **future referrals only**. Existing discount codes retain their original values unless you run the bulk update via the API endpoint `POST /api/shop/:shopId/update-discount-codes`.
***
## Common Scenarios
### "I want ₹150 off for friends and ₹150 cashback for referrers"
* Discount Strategy: **Fixed Amount**
* Discount Amount: `150`
* Referrer Reward: `150`
* Referrer Reward Type: **Cashback**
### "I want 10% off for friends and store credit for referrers"
* Discount Strategy: **Percentage**
* Percentage: `10`
* Referrer Reward: `200`
* Referrer Reward Type: **Store Credit**
* Store Credit Expiry: `90` (expires after 90 days)
### "I want ₹100 off for friends and a ₹100 discount code for referrers"
* Discount Strategy: **Fixed Amount**
* Discount Amount: `100`
* Referrer Reward: `100`
* Referrer Reward Type: **Flat Amount Discount Code**
* After the return period, a unique cart-wide ₹100 discount code is created on Shopify and sent to the referrer via WhatsApp.
### "I want 15% off for friends and a 10% discount code for referrers"
* Discount Strategy: **Percentage**
* Percentage: `15`
* Referrer Reward: `10` (enter 10 for 10%)
* Referrer Reward Type: **Percentage Discount Code**
* After the return period, a unique cart-wide 10% discount code is created on Shopify and sent to the referrer via WhatsApp.
### "I want to allow rewards even if the friend forgets to apply the code"
* Enable **Allow Without Code** — as long as the friend arrived via the referral link, the referrer still earns their reward.