The User Manual has moved! For the most up-to-date information, please visit our new site at
We're committed to providing you with the best resources, and our new site offers an enhanced experience with the latest documentation. Thank you for your understanding and continued support.

The Challenges module enables the rewarding of activities, by monitoring all submitted events (factory and custom events) and creating a new event when pre-determined thresholds have been reached. Challenges can directly award points for reaching such milestones and/or can also be used as triggers in more complex workflows using the built-in workflow editor.

Challenges can be based on various real-world activities, such as ‘Buy at least 3 products at once!’ or ‘Subscribe to our newsletter and read it 3 times a week’. Challenges can be a one-time process or a continual repeatable part of the loyalty program. Challenges are commonly used for badge mechanisms, displaying how many times a customer has performed a certain combination of activities.

Find the configuration page of the Challenges module by clicking the race flag icon in the sidebar or typing 'Challenges' into the search bar of the Modules menu. The page will open to a list of challenges that are already set up, displaying the following information:

  • Name of the challenge
    A text label below the unique ID, specifies if the challenge is Active or Inactive.

  • Type – ‘Hidden custom challenge’ or 'Custom challenge'

  • Points – the number of points that are awarded for completing the challenge

Adding a new challenge

You can access and display all this information on the membership site through the Display API and/or the Entities API. Please consult your developers to implement the necessary calls.

  • Click the ‘Create’ button in the upper right corner of the module page

  • Check the ‘This is a hidden challenge’ checkbox or leave it unchecked if you want to add a card to the membership site and let your customers know that they can complete a challenge
    Please note, that customers' hidden challenge completions are not listed in the response provided by the dedicated Display API endpoint.

  • Click ‘Next’

Basic information

  • Enter the name of the challenge

  • Add a description*
    The description helps customers understand what they need to do in order to complete the challenge.

  • Add a category*
    Select a category from the dropdown menu or create a new one by typing a category name into the field.

  • Upload an image*
    The image must be at least 500×260 pixels in size to ensure your card will look great on both desktop and mobile devices.

  • URL*
    Enter the URL where the customer will be taken after they click on the CTA button on the card.

  • URL target*

    • blank - opening the page on a new browser tab

    • self - opening the page on the current browser tab

    • top - opening the page in the top frame
      For displaying a popup on the redirected site, select this option.

  • Enter a label for the Call-to-Action button

*not applicable to hidden challenges


  • Define the point value
    Specify the number of points you’d like to award customers.

  • Add the points history phrase

  • Set the start and the end date
    Customers can complete the challenge only in the time interval between the start and end dates.

    • Enable ‘Display coming soon’ option
      If the ‘Display ‘coming soon before start date’ option is enabled, the Display API that lists the available challenge for each customer will include the challenge with ‘scheduled’ status before the start date.

  • Restrict the challenge to segments
    By using the dropdown menu, the challenge is applicable for specific customer segment(s) and/or list(s) only. When setting up a challenge to multiple segments, only the or operator is valid, which means that the challenge is completable to the members of any of the selected segment(s) and list(s).

  • Add tag(s) to distinguish this particular challenge from the others
    Select a tag from the dropdown menu or create a new one by typing a tag name into the field.

  • Enable ‘Display challenge only for the selected segment(s)' option*
    Tick the box if you want to hide the challenge from customers who are not in the selected segments.
    If you do not hide the reward, the Display API that lists the available challenges for each customer will include the challenge with restricted' status to customers outside of the selected segment(s) with the default restriction message.

  • Restriction message*
    Let your customers know why they are not eligible, and how they can unlock the challenge.


Specify the action criteria of the challenge. The number of criteria you can add is unlimited.

  • Select the method of calculation

    • Select count to define the criteria based on the number of times the customer has to complete an action with optional attribute conditions and time limitations
      eg. make 2 purchases or write 2 reviews every month for 3 months

    • Select accumulating to define the criteria based on an attribute value of the performed action(s) with a minimum number of actions and optional attribute conditions and a maximum number of actions
      eg. in 4 transactions maximum, the overall checkout total should be 1000 EUR
      Find further examples below.

  • Click the ‘+Add criterium' button

  • Select an event as an action criteria
    Both factory events and custom events (set up in the Custom events module) are applicable.

    • Add filters
      If you want to reward customer actions with specific attributes (e.g., when a customer reviews a specific product), you can add filters with the attribute, the operator, and the value condition

In case you handle multiple accounts in the loyalty program, the ‘Account’ option is available in the ‘Attribute’ dropdown field if you would like to restrict the challenge completion to actions of specific account(s) only.

Further configurable parameters depend on the selected calculation method:

  • Counting challenges

    • Threshold – number of times the user has to complete the action

    • Period – the period of time the user has to complete the challenge
      e.g., ‘1 week’ means that the customer has to complete the challenge within 1 week from the first action taken

    • Interval – the interval in which the user has to take actions
      ‘1 day’ means that the customer must perform the actions every day for the given period

  • Accumulating challenges

    • Minimum number of events
      The customer can complete the challenge if the target attribute value is reached and the customer has completed at least the minimum number of events.

    • Maximum number of events
      The customer can complete the challenge if the target attribute value is reached based on the accumulated values of the maximum number of events.

    • Attribute - the event attribute that should be accumulated
      Please note, that only numeric fields can be used for accumulation.

    • Overall - the accumulated target value of the selected attribute fields of the registered event(s)

  • Add criterium description
    You can inform the customer what they must do in order to complete this particular action.
    Applicable to both accumulating and counting challenges.


  • Enable repeatability by setting an interval in which customers can earn points for completing the challenge
    The minimum interval for repeating the challenge is 1 hour. The repeat interval should be set in the following format: ({number} minute(s)|hour(s)|day(s)|month(s)|year(s))

  • Enable a completion limitation by specifying how many times a customer can earn points for completing the challenge

  • Enable the ‘Resetable’ option to allow challenge reset through the manual registration of a Challenge reset event.
    The Challenge reset event set the current progress attribute value to 0 that is returned by the /customers/{customer_id}/activities/challenges Display API endpoint.

Points economy

  • Select the account to which the points awarded by the challenge will be added
    This configuration field is available if the Multi-accounts module is enabled in the loyalty program.

Saving and activating a challenge

After saving for the first time, the status of the challenge is ‘inactive’, which means it appears only in the list of Challenges on the module configuration page.

You can activate the challenge right away using the ‘Set active’ button on the upper right-hand side of the setup page and confirm the activation in the dialog that subsequently appears.

Translate text

In case you use the Multilanguage module in your loyalty program, the ‘Translate’ buttons are available for you on the challenge editor interface to translate texts to each language enabled. If you don’t specify custom texts, the base text will be applied to all languages.

If you’d like to translate custom challenge fields added through the Custom entities module, make sure the ‘Translatable’ tag is added to the attribute.

Managing challenges

Edit a challenge

  • Navigate to the Challenges tab

  • Click the hamburger button of the challenge that you would like to edit

  • Click ‘Edit’

  • Edit your challenge

  • Save your changes by clicking on the ‘Save’ button

Clone a challenge

If you want to create more challenges with similar settings, you have the option to clone them. This mechanism duplicates all settings.

  • Navigate to the Challenges tab

  • Click the hamburger button of the challenge that you would like to clone

  • Click the ‘Edit’ button of the challenge that you would like to duplicate

  • In the upper right corner, click ‘Clone’
    Once it is done, the editor page of the newly created clone challenge is opened with an 'Activity is successfully cloned.’ success message displayed.

  • Edit the new challenge as necessary

  • Click ‘Save’

Deactivate a challenge

If you choose to remove the challenge from the list of point-earning options before the end date, you can deactivate it anytime:

  • Navigate to the Challenges tab

  • Click the hamburger button of the challenge you want to deactivate

  • Click on the ‘Set inactive’ button on the upper right-hand side of the page

  • Confirm your choice in the dialog that appears

Archive a challenge

You have the option to delete inactive challenges from the Backoffice by archiving them.

  • Navigate to the Challenges tab

  • Click the hamburger button of the inactive challenge you want to archive

  • Click on the ‘Archive’ button on the upper right-hand side of the page

  • Confirm your choice in the dialog that appears

Archiving is irreversible. Once a challenge is archived, it cannot be restored anymore.

Import challenges

Challenges can be created or updated through the Imports module as well.
As the import process does not include image upload, please make sure you add the image(s) using the ‘Image’ field, to be able to display them to customers properly.

Sorting of challenges

You can define the order of the challenges on the membership site by selecting the ‘Sorting’ option in the sidebar. The list of the flows returned by the Display API will be ordered based on the sorting set.
Just drag and drop the flow to change the order, and the changes are automatically applied.

Filter challenges

Filter your challenges in the Backoffice by clicking the ‘Filters’ button at the top right corner of the module configuration page. Select the status(es) that you’d like to filter to and click ‘Apply’ to see the filtered list or ‘Reset’ to close the filter menu and see the entire list again.

Searching for a challenge

Use the search bar to search for a specific challenge name in the challenge list on the Challenges module page.

Challenge statistics

View detailed reports on how your activities are performing individually. To reach the ‘Statistics’ page of a challenge, go to the Challenges module configuration page, click the hamburger button of the challenge, and navigate to the ‘Statistics’ page.

On this page, you can find numbers detailing the performance of a challenge during the selected timeframe.

  • Total number of challenge completions

  • Number of members who have completed the challenge

  • Number of points earned by completing the challenge

  • Graph of the number of completions

Challenge completions

Check the full customer list and timestamps of challenge completions by going to the Challenges module configuration page, clicking the hamburger button of the challenge, and navigating to the ‘Completions’ page.

Exporting challenges

It is possible to export challenges for further analysis and reporting purposes using the exports module.

  • Go to the Exports module page, choose ‘Challenges’ as the data model, and click ‘Next’.

  • Follow the steps of the Exports user manual on how to create the Challenge export.


© Copyright 2022 Antavo Ltd.