> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a challenge

> Build a challenge inside a campaign, one tab of the form at a time, from an empty form to published.

Use a challenge to reward customers for buying, visiting or paying in a set way. This page takes you through creating one in Lobyco Nexus, from an empty form to published.

> [!NOTE]
>
> A challenge always belongs to a campaign, so create or open the campaign first.

## Add a challenge to your campaign

You can add a challenge in the campaign's list or on its [orchestration canvas](/business-documentation/campaigns/orchestration-canvas). Either way, the same form opens.

**In the list**

1. Go to **Campaigns** and open the campaign the challenge belongs to, or [create a new one](/business-documentation/campaigns/create-a-campaign).
2. Select **Add activities**, or **Add activity** if the campaign already has some.
3. On the **Select an activity** page, point at the **Challenge** tile and select **From scratch**. To start from a saved challenge instead, select **From template**. [Reuse with templates](/business-documentation/campaigns/reuse-with-templates) explains how.

**On the canvas**

1. Go to **Campaigns** and open the campaign the challenge belongs to, or [create a new one](/business-documentation/campaigns/create-a-campaign).
2. Select **Orchestration** at the top.
3. In the **Block library**, drag a **Challenge** block from the **Activity** group onto the canvas.
4. Double-click the block. **Create Activity** opens.
5. Select **From Scratch**. To start from a saved challenge instead, select **From Template**. [Reuse with templates](/business-documentation/campaigns/reuse-with-templates) explains how.

Once you've saved the form, you can connect the block to the rest of the flow. Then select **Save** at the top right of the canvas.

A challenge block works without any connection. Left on its own, it isn't triggered. Every customer in its **Segmentation** can take part.

* **Input.** The block takes one link. It can come from a **Delay**, or from any block that passes on customers, listed as **Customers only** or **Customers plus attributes** in [What can connect to what](/business-documentation/campaigns/orchestration-canvas/block-reference#what-can-connect-to-what). A **Split** can't connect straight in, so connect one of its branches. A **Member segment** with a split configured can't connect straight in either. When a block connects into the challenge, it becomes a triggered challenge, with extra fields on [Activity details](#fill-in-activity-details).
* **Output.** The block's output port, and the port on each coupon reward, connect to an **Activity event** block. That block starts a flow when a customer completes a card.

Connect the block before you publish the challenge. After you publish, the portal refuses to connect or disconnect it, and asks you to bring the challenge back to draft first. To change the links later, [disable the challenge](/business-documentation/activities/challenges/edit-or-disable-a-challenge#stop-a-challenge), change the links, and publish again. While the challenge is a draft, purchases don't count toward it.

The form has four tabs, in this order: **Activity details**, **Settings**, **Challenge layout** and **Segmentation**. A tab's number turns red while something on it still needs filling in. It shows a tick once you've been through the tab and it's complete.

![The Create Challenge form as it opens, with four numbered tabs across the top: 1 Activity details, 2 Settings, 3 Challenge layout and 4 Segmentation. Activity details is open, its number in red, and every field is empty: Activity name, with Max. 64 characters under it, Start date and End date, Display priority set to 5, Chain(s) OR Store(s), each with an upload button, and Assign a tag. Cancel sits at the bottom left, and Save and Publish are greyed out at the bottom right.](https://mintcdn.com/lobyco-4c9fb3ad/rG971_5ZfS49bcjM/images/challenges-01-form-as-it-opens.png?fit=max\&auto=format\&n=rG971_5ZfS49bcjM\&q=85\&s=3eb1f0da3348a790b5cd8343499240ce)

*The challenge form as it opens*

## Fill in Activity details

| Field | What it does |
| - | - |
| **Activity name** | Required. Names the challenge in Nexus. Up to 64 characters. Names don't have to be unique. A naming convention makes challenges much easier to find later, for example `2024_week_42_Buy10Get1milk`. |
| **Start date** / **End date** | Required. Sets the date and time the challenge starts and ends. Customers see the challenge in the app only between the two, and only purchases made between them count. Both must fall inside the campaign's dates, which the form shows under each field. |
| **Display priority** | Required. Sets where the challenge shows among others in the app, from 1 to 10. 1 shows first. It starts at 5, so you can rank other challenges above or below it. Challenges with the same priority show in the order your app uses by default. A challenge created before this field existed counts as 5 until you edit it. |
| **Chain(s)** or **Store(s)** | Required. Sets where purchases count toward the challenge. Pick chains or stores, not both. Choosing one turns the other off. Both fields take a CSV upload, with one ID per line. You can also download what you've selected. |
| **Assign a tag** | Optional. Groups the challenge with other content in the app. Pick one or more tags from the list. The list is part of your setup, so you can't create tags in Nexus. |

> [!TIP]
>
> Set the start time to 00:01 and the end time to 23:59, so it's clear which days count. Both fields take a time as well as a date.
>
> You can pick a start time in the past, but Lobyco doesn't go back for purchases it has already processed. Only purchases processed after you publish count.

When another block on the orchestration canvas connects into the challenge, it becomes a *triggered* challenge. This tab then adds an **Add triggered details** panel with these fields:

* **Validity period of challenge** is how many days a customer has to complete the challenge after they receive it. If you leave it empty, the customer has until the challenge's end date.
* **Time between challenges issued** and **Specify timeframe** set how long before the same customer can receive the challenge again. Enter a number, then pick **Day(s)**, **Week(s)**, **Month(s)** or **Year(s)**.

## Set how progress is earned

Open **Settings**. Its first panel, **Activity behaviour**, decides what customers have to do.

| Field | What it does |
| - | - |
| **Challenge type** | Sets how many goals the challenge has. **Standard**, the default, has one goal and one set of rewards. **Tiered** has several goals, each with its own rewards. See [Tiered challenges](#tiered-challenges). |
| **Pre-activated** | Sets whether customers have to activate the challenge first. It's off by default, so each customer activates the challenge in the app. Turn it on and customers start collecting progress automatically when the challenge starts. |
| **Hide Challenge from App List** | Keeps the challenge out of the app's list and home screen. The challenge still tracks progress and gives rewards as usual. |
| **Accumulation** | Sets how progress adds up. Pick **One purchase**, **Multiple purchase**, **Store visits** or **Payment method**. The earn rules change with it. [Accumulation types](/business-documentation/activities/challenges/accumulation-types) explains each one. |
| **Earn rules** | Sets what counts toward progress, and how much of it is needed. A standard **One purchase** challenge can have several rules. You add each one with **Add Rule**. Every other kind of challenge has one rule. |
| **Delay between purchases** | Sets how many hours must pass after a counted purchase or a refund before the next purchase counts. A refund restarts the delay. Leave it empty for no delay. [Delay between purchases](/business-documentation/activities/challenges/accumulation-types#delay-between-purchases) explains it. |
| **Checkout types** | Limits progress to purchases made through **POS**, **Self-checkout**, **Scan & Pay** or **E-commerce**. If you select none, every checkout type counts. Once you select some, a purchase your POS sends without a checkout type doesn't count. |
| **Specify if the challenge should be one-time or renewable** | Sets whether a customer can complete the challenge more than once. **One-time** allows one completion. **Auto-renewable** allows as many as you set in **Total number of cards issued**, which is at least 2. **Unlimited**, the default, allows any number until the end date. [One-time or renewable](/business-documentation/activities/challenges/accumulation-types#one-time-or-renewable) explains each one. |
| **Discounted items behaviour during challenge progress** | Sets whether discounted items count toward progress. **Include Discounted Items** is the default, and counts discounted items too. On a **Purchase amount** rule, they add the price the customer paid. **Exclude Discounted Items** counts only full-price items. This field isn't shown for **Store visits**, and it has no effect on **Payment method**. See [Discounted items](/business-documentation/activities/challenges/accumulation-types#discounted-items). |

> [!TIP]
>
> Turn on **Pre-activated** whenever you hide the challenge. A hidden challenge isn't in the app's list, so a customer has nowhere to activate it.

> [!WARNING]
>
> Choose **Accumulation** and **Challenge type** before you set earn rules or rewards. Changing either later can clear them, sometimes without asking first.

Changing **Accumulation** resets your earn rules. [Changing the accumulation later](/business-documentation/activities/challenges/accumulation-types#changing-the-accumulation-later) says what each one keeps.

Nexus asks you to confirm in two cases only:

* The challenge has more than one earn rule, and you change **Accumulation** or switch **Challenge type** to **Tiered**. Both keep only the first rule.
* You switch a tiered challenge that has rewards on its tiers back to **Standard**.

In every other case it changes without asking. For example, switching a standard challenge with one earn rule to **Tiered** clears its reward without asking.

### Tiered challenges

A tiered challenge sets a series of goals on one earn rule, such as spend 50, then 100, then 200. Each goal has its own rewards, for example 5 bonus points, then 15, then a 20% off coupon. Every tier shares the products, categories and earn method you set above.

1. Set **Challenge type** to **Tiered**. The form starts you with two tiers. A tiered challenge always has at least two.
2. For each tier, enter its target. Depending on the earn rule, that's a **Count**, an **Amount**, or a number of visits or purchases. Each tier's target has to be higher than the one before.
3. On each tier, select **Add rewards**. Tick any combination of **Coupon reward**, **Bonus reward** and **Custom reward**. Fill in what each one needs, then confirm with **Select**. A tier can hold one coupon, one bonus and one custom reward, but not two of the same kind. Every tier needs at least one reward. To change a tier's rewards later, select **Edit**.
4. To add more goals, select **Add tier**. Once there are more than two tiers, you can delete any of them.

**Reward issuance behaviour** has two options. You can't change it once the challenge is published, even while it's still scheduled.

* **Issue at every tier crossed** is the default. It gives the customer each tier's rewards as soon as they reach its target. A purchase that crosses several tiers gives the rewards of all of them.
* **Issue only the highest tier** gives only the rewards of the highest tier the customer reaches. A customer who reaches the top tier gets its reward straight away, and the card completes. A customer who stops lower down gets the rewards of their highest tier in the overnight run after the challenge ends, and the lower tiers they passed give nothing. Purchases that reach Lobyco after that run, such as sales a store system sends late, don't change it. If the challenge is disabled when the run happens, those customers get nothing. See [Stop a challenge](/business-documentation/activities/challenges/edit-or-disable-a-challenge#stop-a-challenge).

A **One purchase** challenge always issues at every tier crossed, so the field is greyed out.

How a card completes depends on **Accumulation**.

* On **Multiple purchase**, **Store visits** and **Payment method**, a card completes when the customer reaches the top tier. On a renewable challenge, the customer then starts a new card at the first tier, and any progress beyond the top tier carries over to it.
* On **One purchase**, each purchase is judged on its own, and progress doesn't carry over to the next purchase. The purchase completes the card at the highest tier it reaches, even if that isn't the top one. If the challenge is **One-time**, the customer can't come back for a higher tier.

For example, take a **Multiple purchase** challenge on **Product quantity**, **One-time**. Tier 1 is 5 coffees for 10 bonus points, and tier 2 is 10 coffees for 25 bonus points.

| Purchase | Coffees | Running total | **Issue at every tier crossed** | **Issue only the highest tier** |
| - | - | - | - | - |
| 1 | 3 | 3 | Nothing | Nothing |
| 2 | 3 | 6 | 10 points | Nothing yet |
| 3 | 4 | 10 | 25 points, card complete | 25 points, card complete. The 10 points are never given. |
| Customer stops after purchase 2 | | 6 | 10 points, straight away | 10 points, in the overnight run after the challenge ends |

On a **One purchase** version of the same challenge, each purchase stands alone:

* 4 coffees reach no tier, and give nothing.
* 7 coffees reach tier 1, and complete the card with 10 points.
* 12 coffees reach tier 2, and complete the card with 10 + 25 points.

A tiered challenge also uses **Specify if the challenge should be one-time or renewable**. **Pre-activated**, **Delay between purchases** and **Discounted items behaviour during challenge progress** work as they do on a standard challenge. They apply to the whole challenge, not to each tier. Setting **Redeemable only in the store where the challenge was completed** on a tier's coupon applies to that tier's coupon only.

If any tier has a bonus reward, set **Bonus sponsor**. It applies to every bonus on every tier. A tiered challenge can't be a lottery, and it doesn't offer **Add Rule**.

## Choose the reward

For a standard challenge, you set the reward in **Activity reward**, the second panel on **Settings**. A tiered challenge doesn't show this panel, because its rewards sit on each tier.

First, decide how customers get the reward, in **Select reward types**. **Standard** is selected when you open the form, and no reward is ticked yet. This **Standard** is the reward type. It isn't the **Standard** challenge type, and a tiered challenge always uses a **Standard** reward.

| Option | What it does |
| - | - |
| **Standard** | Customers get the reward as soon as they complete the challenge. |
| **Global Lottery** | Winners are drawn after the challenge ends, and get their rewards once you approve the draw. |
| **Local Lottery** | The same as **Global Lottery**, but winners are drawn per store. This gives customers a reason to shop in more stores. Each reward's **Total rewards** is per store, so 10 rewards in 20 stores is up to 200 prizes. A store with fewer entries than prizes has fewer winners. See [How a local lottery picks winners](/business-documentation/activities/challenges/draw-lottery-winners#how-a-local-lottery-picks-winners). |

> [!WARNING]
>
> Settle **Challenge type** and **Select reward types** before you publish.

You can't change either of them once the challenge is **Active**. Nexus also won't save a change to **Select reward types** once the challenge is published, even while it's still scheduled.

Then tick the reward. A challenge with a **Standard** reward gives one kind of reward, so ticking a second one replaces the first. A lottery can combine all three.

| Reward | With a **Standard** reward | In a lottery |
| - | - | - |
| **Coupon reward** | Pick one offer from the table of offers you can use. | Tick each offer you want to include, and set its **Total rewards**. In a **Local Lottery**, that's per store. |
| **Bonus reward** | Enter the **Bonus amount** the customer receives. | Fill in a **Name**, a **Bonus value** and the **Total rewards** for each prize. The first row is already there. Select **Add reward** to add another. In a **Local Lottery**, **Total rewards** is per store. |
| **Custom reward** | Nothing more to fill in. You deliver the reward yourself, outside the app. To find who earned it, see [Find who earned a custom reward](#find-who-earned-a-custom-reward). | Fill in a **Name** and the **Total rewards** for each prize. The first row is already there. Select **Add reward** to add another. In a **Local Lottery**, **Total rewards** is per store. |

The coupon table only lists published offers of type [**Challenge**](/business-documentation/activities/offers/offer-types) that run at least until the challenge's end date. If your offer isn't there, publish it, check its type, or bring the challenge's end date forward. An offer that starts after your challenge starts is listed, but you can't publish the challenge. Move the challenge's **Start date** to the offer's start or later.

If you pick a **Custom reward**, say in **Details text** or **Terms & conditions text** how and when you'll deliver it.

Two more fields appear, depending on the reward:

* **Redeemable only in the store where the challenge was completed** appears under **Coupon reward** once you tick it. On a tiered challenge it's in each tier's **Add rewards** window. It limits the coupon to the store where the customer completed the challenge.
* **Sponsor** appears under **Bonus reward**, and it's required. It records who paid for the bonus, so you can report on it. The list of sponsors is part of your setup, so you can't add a sponsor in Nexus.

For coupon and bonus rewards, the **Redemption** panel sets how long the customer can use the reward. That goes for a standard challenge and for any tier. Neither field is required. Fill in only one of the two. Once you fill in one, you can't fill in the other.

* **Redemption expire date** is a fixed date. It can't be before the challenge's end date. For a coupon reward, it also can't be after the end date of the earliest-ending offer you picked.
* **Validity period of redemption** is a number of days. The reward expires at the end of the day that many days after the day the customer gets it. In a lottery, the customer gets it on the day you approve the draw. For a coupon reward, the challenge's end date plus this number of days can't be after the end date of the earliest-ending offer you picked. For example, if the challenge ends on 30 June and the offer ends on 15 July, the most you can enter is 15 days.

If you leave both empty, a coupon reward takes its offer's **Validity period**, counted from the day the customer gets it, and never runs past the offer's end. If the offer has no **Validity period**, the coupon lasts until the offer ends. A bonus reward with both fields empty gets no expiry date from the challenge.

![The Settings tab of a new standard challenge, scrolled to Activity reward. Select reward types is set to Global Lottery, and all three rewards are ticked: Coupon reward, with Redeemable only in the store where the challenge was completed unticked under it, Bonus reward and Custom reward. The Coupon reward table says only coupons whose date range covers or extends beyond the activity period appear in it. It lists five test offers with their Id, Chain and Period, and the first, ChallengeReward, is ticked with Total rewards 20. The Bonus reward table has one row, 500 bonus points, with Bonus value 500 and Total rewards 50, and Sponsor below it is set to Retailer. The Custom reward table has one row, Coffee machine, with Total rewards 1. Both tables have an Add reward link and a bin icon on the row. Below, the Redemption panel offers Redemption expire date OR Validity period of redemption, both empty.](https://mintcdn.com/lobyco-4c9fb3ad/rG971_5ZfS49bcjM/images/challenges-02-lottery-rewards.png?fit=max\&auto=format\&n=rG971_5ZfS49bcjM\&q=85\&s=fb6ec3af895dbd0e8ba628bfb29fecc1)

*A global lottery with all three kinds of reward*

At the top of a saved challenge, **Details** holds the form you've just filled in. Once you save a lottery challenge, a **Lottery** tab appears beside **Details**. That's where you draw the winners after the end date. See [Draw lottery winners](/business-documentation/activities/challenges/draw-lottery-winners).

### Find who earned a custom reward

Download the [challenge report](/business-documentation/activities/challenges/challenge-report). It only exists for **Active** and **Expired** challenges. A completed card shows **ClosedAt** on every one of its rows, so filter to the rows with a filled **ClosedAt** and list each **MemberId** once. The report has no contact details. To contact a customer, search for the ID under **Member management → Members**.

## Design the challenge card

Open **Challenge layout**. The **Preview** beside the fields shows where each one lands on the challenge card and its details page. It isn't the final design.

| Field | What it does |
| - | - |
| **Product image** | Required. PNG or JPEG, up to 2 MB. Place the product on a 300 × 300 px square with a transparent or white background, at least 25 px from every edge. |
| **Card background image** | Optional. The same formats and size limit as **Product image**. |
| **Crop image** | Appears under an image once you upload it. Lets you crop, rotate or zoom the image without uploading it again. |
| **Card name** | Required. The challenge's name as customers see it. Up to 250 characters. |
| **Challenge progress and reward label** | Optional. A short line about progress and the reward, for example *Buy 4, get 1*. Up to 30 characters. |
| **Challenge completion counter label** | Optional. Shows how many times the customer has completed the challenge. Put `%counter%` where the number goes, for example *Completed times: %counter%*. Up to 40 characters. |
| **Details text** | Required. Describes the challenge to customers. |
| **Terms & conditions text** | Required. The terms that apply, such as limited stock or special conditions. |

![The Challenge layout tab of a new challenge, filled in, with the Preview on the right. On the left: a coffee machine picture as the Product image and a beige pattern as the Card background image, each with a Crop image button under it. Below them, Card name reads Win a coffee machine, Challenge progress and reward label reads Buy 3 coffees, and Challenge completion counter label reads Lottery tickets: %counter%. Details text and Terms & conditions text describe the prize draw. On the right, Preview layout shows the card as it looks in the app's list: the beige background along the top with a Buy 3 coffees label, the coffee machine in a circle, the card name and an Activate button. Details layout below shows the challenge's details page: the card name, the coffee machine with a round Buy 3 coffees badge, a Lottery tickets: 3 counter, the Details and Terms & conditions texts, and Activate. Preview carries the note Actual design may differ.](https://mintcdn.com/lobyco-4c9fb3ad/rG971_5ZfS49bcjM/images/challenges-03-layout-and-preview.png?fit=max\&auto=format\&n=rG971_5ZfS49bcjM\&q=85\&s=f415a224ac8e665beef59942a8ee3760)

*Challenge layout, with the card and its details page in the preview*

## Choose who can take part

Open **Segmentation** and pick one of these:

* **All customers** is the default. Every customer can take part.
* **Target only selected segment** limits the challenge to one or more segments. Pick one or more with **Select from list**, or make a new one there with **Create new audience**. A customer who is in several of the segments you pick still gets one card, and their progress and rewards aren't doubled. The list only shows segments whose **Destination(s)** include **Challenges**. You build segments in [Segments and Audiences](/business-documentation/audiences-and-data).

For a triggered challenge, this tab is locked. The block that connects into the challenge on the canvas decides who receives it.

## Save or publish the challenge

At the bottom of the form:

* Select **Save** to keep the challenge as a draft while you work on it. A draft needs an **Activity name**, a **Start date** and **End date**, and a target on every earn rule. On a tiered challenge, that means a target on every tier. It doesn't need a reward. On a tiered challenge, once one tier has a reward, every tier needs one. Anything else you've filled in has to be valid.
* When every tab is complete, select **Publish**, and confirm. The confirmation tells you whether the challenge becomes active now or on its start date. If you added the challenge on the canvas, [connect its block](#add-a-challenge-to-your-campaign) first, because you can't connect it after you publish.
* Select **Cancel** to close the form without keeping your changes.

Once you've published, the form closes and you're back in the campaign's activity list. The challenge's **Status** there shows **Scheduled** until its start date, then **Active**.

To keep the challenge as a template, see [Save as template](/business-documentation/activities/challenges/edit-or-disable-a-challenge#save-as-template). On a published challenge, **Save** keeps your edits, and **Unpublish** turns the challenge back into a draft. **Delete** appears once the challenge has been saved. You can only delete a draft. See [Edit or disable a challenge](/business-documentation/activities/challenges/edit-or-disable-a-challenge).

## Troubleshooting

> **Why can't I edit this challenge?**
>
> The form is read-only when the challenge has expired, when its campaign has ended, or when you open the challenge outside a campaign. Open it from the campaign instead, while the campaign is still running.

> **Why won't the challenge publish with my coupon reward?**
>
> The coupon's dates have to fit around the challenge. The challenge can't start before the offer does. The reward also has to expire by the offer's end date. That goes for the **Redemption expire date**, and for the challenge's end date plus the **Validity period of redemption**. The form checks the **Redemption expire date** as you type. It only checks the **Validity period of redemption** when you save or publish.

## Related

* [Accumulation types](/business-documentation/activities/challenges/accumulation-types) — each way progress can add up, and the earn rules for each.
* [Draw lottery winners](/business-documentation/activities/challenges/draw-lottery-winners) — drawing, checking and approving winners once a lottery challenge ends.
* [Edit or disable a challenge](/business-documentation/activities/challenges/edit-or-disable-a-challenge) — what can still change once a challenge is live, and how to stop one.
* [Offer types](/business-documentation/activities/offers/offer-types) — the **Challenge** offer type behind a coupon reward.
* [Reuse with templates](/business-documentation/campaigns/reuse-with-templates) — starting a challenge from a saved one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.