Achievement Definitions

{
    "data": [
        {
            "id": 1,
            "name": "Become a favourite",
            "handle": "favourite",
            "description": "Unlocks special rewards for favourites",
            "internal_notes": null,
            "type": null,
            "starts_at": "2020-03-10T00:00:00.000000Z",
            "ends_at": "2021-06-25T00:00:00.000000Z",
            "is_published": true,
            "display_level": true,
            "display_option": "visible",
            "short_description": "favourite",
            "long_description": "<h3><strong>Become a Favourite</strong></h3>",
            "terms_conditions": "<p>Terms and Conditions</p>",
            "earn_instructions": null,
            "icon": "https://icons.example.com/1",
            "image_url": "https://images.example.com/1",
            "levels": [
                {
                    "id": 7,
                    "name": "favourite 1",
                    "achievement_definition_id": 1,
                    "display_number": 1,
                    "description": null,
                    "trigger": 5000,
                    "repeats": 0,
                    "repeat_interval": null,
                    "allow_multiple_earn": true,
                    "computed_display_number": null,
                    "computed_trigger": null,
                    "meta": {
                        "unlocks": [
                            {
                                "id": "level-1",
                                "type": "benefit_definition",
                                "id_type": "handle"
                            }
                        ]
                    }
                },
                {
                    "id": 8,
                    "name": "Level 2",
                    "achievement_definition_id": 1,
                    "display_number": 2,
                    "description": null,
                    "trigger": 8000,
                    "repeats": 0,
                    "repeat_interval": null,
                    "allow_multiple_earn": true,
                    "computed_display_number": null,
                    "computed_trigger": null,
                    "meta": {
                        "unlocks": [
                            {
                                "id": "favourite-2",
                                "type": "benefit_definition",
                                "id_type": "handle"
                            }
                        ]
                    }
                }
            ],
            "tags": [],
            "meta": null,
            "created_at": "2019-12-09 11:29:04",
            "updated_at": "2020-05-14 12:33:44"
        }
    ],
    "links": {
        "first": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions?page.number=1",
        "last": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions?page.number=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

What is an achievement definition?

Much like point definitions, achievement definitions are a configurable ‘template’ used when adding a profile achievement. Use Add Achievement Definition to specify your new type of achievement. After this, you can then Add a Profile Achievement to a profile, using your newly created definition.

See Achievements for a full explanation of how achievement definitions, levels, and profile achievement instances work.

Achievement definition properties

Attribute	Description
id `READ-ONLY` `INTEGER`	The unique Omneo ID for the definition
name `STRING`	The display name of the definition
handle `STRING`	A unique handle for the definition
description `STRING`	The internal description for the definition
internal_notes `STRING`	Internal notes attached to the definition
type `STRING`	A basic string displaying the type of definition.
starts_at `DATE-TIME`	The published start of the achievement. With `is_published`, this governs when the achievement is presented to customers. It does not gate earning — see What the dates do and do not do
ends_at `DATE-TIME`	The published end of the achievement. After this date the achievement is no longer presented as currently earnable. It does not gate earning — see What the dates do and do not do
is_published `BOOLEAN`	Denotes whether this achievement is published
display_level `BOOLEAN`	Display the achievement levels to users
display_option `STRING` `ENUM`	* Standard* - can be seen by the customer along with instructions on how to earn * Hidden* - are not seen until ‘unlocked’ by the customer receiving a count of 1 or more * Mystery - are seen as earnable with optional ‘hint’ copy but not revealed until unlocked System *- are never seen by customers, but can be used to power more advanced incentive logic or reporting
short_description `STRING`	A publicly available short description for this definition
long_description `STRING`	A publicly available full HTML description of the definition
terms_conditions `STRING`	The terms and conditions associated with the achievement
earn_instructions `STRING`	Instructions displayed to the customer, on how to earn this achievement
icon `URL`	A valid URL for the icon associated with this definition
image_url `URL`	A valid URL for the cover image associated with this definition
levels `ARRAY`	Achievement levels attached to this definition. Review the below ‘Creating Achievement Levels’ Sec

What the dates do and do not do

starts_at and ends_at are a presentation contract. They describe the window in which the achievement is offered to customers. They are not enforced anywhere in the earning path.

starts_at and ends_at do not block achievement progress. Neither field is evaluated when a count is incremented, so:

A direct POST to Add a Profile Achievement succeeds outside the window.
A reaction running achievement.increment or achievement.increment.transaction increments regardless of the window, and any level crossed will issue its unlocked rewards or benefits.

If a campaign must only count activity inside a date range, the date test belongs in the reaction’s filter action. See Date-gating a campaign.

This bites hardest with batched or replayed transactions. A POS batch delivered tonight can carry sales transacted days ago; the reaction fires when the batch lands, not when the sale happened. Gate on the transaction’s own transacted_at, never on when Omneo received it.

Creating Achievement Levels

Triggers

Triggers type levels will grant a level when the achievement count reaches the trigger value. These are granted only once and are used for a fixed achievement path.

Repeating

Repeat type levels will grant an achievement sequentially based on repeat interval. Used for campaigned such as ‘Earn achievement for every 5 shops’ etc. A repeats value of 0 will continue indefinitely. Any other number will stop granting levels after that number is reached.

Achievement Level Fields

Attribute	Description
id `READ-ONLY`	The unique Omneo ID of the achievement level
name	The display name of the level
achievement_definition_id	The attached achievement definition for this level
display_number `INTEGER`	The display order of the level
description `STRING`	The primary description for the level
trigger `INTEGER`	The value the achievement count must reach to grant the level
repeats `BOOLEAN`	Denotes whether this level is repeatable
repeat_interval `INTEGER`	A repeats value of 0 will continue indefinitely. Any other number will stop granting levels after that number is reached.
allow_multiple_earn `BOOLEAN`	Can this level be earned multiple times
meta `ARRAY`	Metadata attached to this level

Overview

Authentication

Profiles

Commerce

Incentives

Lists

Groups

Ratings and Interactions

Reactions

Organisations and access

Configuration

Platform

Questionnaires

Achievement Definitions

What is an achievement definition?

Achievement definition properties

What the dates do and do not do

Creating Achievement Levels

Triggers

Repeating

Achievement Level Fields

​What is an achievement definition?

​Achievement definition properties

​What the dates do and do not do

​Creating Achievement Levels

​Triggers

​Repeating

​Achievement Level Fields

What is an achievement definition?

Achievement definition properties

What the dates do and do not do

Creating Achievement Levels

Triggers

Repeating

Achievement Level Fields