Working with Benefits

Before you begin

We recommend you review these articles to familiarise yourself with the different incentives Omneo offers.

[Rewards] (https://help.omneo.io/hc/en-au/articles/360000426095-Rewards)
[Tiers] (https://help.omneo.io/hc/en-au/articles/360000426115-Tiers)
[Achievements] (https://help.omneo.io/hc/en-au/articles/360000426075-Achievements)
[Benefits] (https://help.omneo.io/hc/en-au/articles/360000038395-Benefits)

Working with Benefits

Applying a benefit to an account can be summarised into the below steps:

Create a Benefit Definition (If you already have one, you can skip this)
Create the benefit, assigning it to a profile
Create a redemption of the reward
Create a transaction and link it to the redemption

Create a Benefit Definition

Benefit definitions explain what your reward is and how it should be used.
Similar to Reward Definitions, Benefit Definitions contain all the key information about a benefit.

To create a definition, we can use the Add Benefit Definition endpoint.
With the below payload:

Note down the id of your definition

{
    "name": "First Spend Discount",
    "period": "7",
    "handle": "first-spend",
    "description": "Member first spend 10% discount",
    "internal_notes": "Only assigned to members with no transactions",
    "short_description": "Get 10% off your first spend with us!",
    "long_description": "<p>Get 10% off your first shop. Valid for 7 days </p>",
    "terms_conditions": "Terms and conditions apply",
    "earn_instructions": "After signing up, get 10% off your first shop",
    "redeem_instructions_store": "Can be redeemed in store",
    "redeem_instructions_online": "Can be redeemed online",
    "icon": "http://example.com/icon",
    "image_url": "http://example.com/image",
    "max_redemptions": "1",
    "is_extendable": false,
    "is_reassignable": false,
    "tags": [
        "first_spend",
        "new_member"
    ],
    "is_published": true,
    "is_archived": false
}

You've now created your benefit definition.
You don't have to create a definition each time, if you're redeeming the same type of benefit we've created above. If you were to create a new type of benefit, you would need a new defenition.

Create a benefit, and assign it to a profile.

Now that we've created our definition, we still need to create the bebefit.
When creating a benefit, you need to specify the definition to use.
You can create a bebefit using the Add Benefit endpoint.
Make sure to substitute your profile_id into the below request

Note down the id of your reward

{
    "benefit_definition_id": 94,
    "profile_id": "92a7996b-abb6-4c9c-a845-9aaf8202fab6",
    "issued_at": "2021-03-10 06:47:47",
    "timezone": "Australia/Melbourne"
}

So far, we've created the definition and assigned a benefit to the definition.

If you take a look in your available benefits in your Omneo CX Manager, you'll see there is an available benefit, with 1 active instance.

Now that we have an available benefit, you can use the Browse Profile Benefits endpoint to see all available benefits against our profile. You can also use Read Profile Benefit to get single benefit on the profile by id

Add a benefit redemption

After identifying the available benefits on the profile using the endpoints mentioned above, we can now go ahead and redeem one from the profile.
For example, you may be developing an Omneo integration for a POS system, you could use the Browse Profile Benefits endpoint to identify the benefits when you select the customer account, then use the Add Benefit Redemption to redeem the benefit once selected.

The below is an example of calling the Add Benefit Redemption to redeem a benefit available on a profile.

profile your profile_id and benefit_id as part of the URL of the endpoint
Note down the redemption id, you will need this to attach to a transaction

{
    "issued_at": "2021-01-10 06:47:47",
    "benefit_definition_id": "94",
    "profile_id": "92a7996b-abb6-4c9c-a845-9aaf8202fab6",
    "timezone": "Australia/Melbourne",
    "external_id": "12400130",
    "expires_at": "2021-03-10 06:47:47" 
}

So far we've created a definition, created a benefit, and redeemed the benefit on the profile
You'll notice now, this profile's available reward balance is now $0, because we've just redeemed the balance in the previous step. We're not done yet!
If you go back to Benefit management in your Omneo CX Manager, the benefit we saw previously now has 0 active instances. This is because we've just redeemed it from the profile. This was the only profile with the benefit active.

Attach a benefit to a transaction

The final step is to add this reward to a transaction. If this was a manual redemption, you won't have a transaction, so this is unnecessary. However, we are simulating that this customer purchased something from a store and some logic was applied at the POS to receive a 10% discount.

We will need to create a transaction with the Add Transaction API endpoint.
make sure the redemption_id matches the id of your reward redemption in the previous step

{
    "total": "10",
    "profile_id": "{YOUR_PROFILE_ID}",
    "transacted_at": "2021-02-10 00:00:00",
    "timezone": "Australia/Melbourne",
    "items": [
        {
            "name": "A very nice bag",
            "product_variant_id": "1",
            "quantity": "1",
            "price_current": 99.99,
            "price_sell": 89.99,
            "is_void": false,
            "price_original": 99.99,
            "price_margin": 1,
            "tags": ["fashion"]
        }
    ],
    "redemption_id": 159,
    "external_id": "91040898233311",
    "total_original": 99.99,
    "is_void": false,
    "margin": 1
}

Finally, navigate to the transaction in your Omneo CX Manager,
and you'll notice that your new transaction, has a discount applied.