Claimable Benefits
A claimable benefit can be issued by a customer by a link. Usually via a banner on a website, email or via social media.
Different to regular benefits, a claimable benefit allows the customer to issue the benefit against their profile. Claimable benefits are slightly different to regular benefits, which are issued by the Omneo system via reactions or similar mechanics.
The lifecycle of a claimable benefit can be broken down into the following:
- Creation of claimable benefit definition
- Define the claimable logic, and custom barcodes if required.
- Display available benefits to customer
- Redeem benefits.
In this example, we will be creating a claimable benefit, giving customers 10% off their next purchase.
this voucher will be available for 50 days.
Creating a claimable benefit
Like all benefits we first need a Benefit Definition, to act as our template. Instances of this benefit are then assigned to profiles from this definition.
Create the definition
Using the Add Benefit Definition endpoint,
enter the following payload:
{
"name":"10%OFFDEMO",
"handle":"10offdemo",
"period":50,
"description":"10% off",
"internal_notes":"demo",
"short_description":"A quick 10% off",
"long_description":"Just another 10% voucher for you",
"terms_conditions":"standard terms and conditions apply",
"earn_instructions":null,
"redeem_instructions_store":null,
"redeem_instructions_online":null,
"redeem_code_pos":"10OFFSTORE",
"redeem_code_online":"10OFFONLINE",
"icon":null,
"image_url":"https://example.com/image.jpeg",
"max_redemptions":1,
"is_extendable":false,
"is_assignable":true,
"is_reassignable":false,
"is_published":true,
"is_archived":false,
"tags":[
"demo"
],
"is_claimable":true,
"max_global_redemptions":null,
"claim_period_start_at":"2020-12-25 07:00:00",
"claim_period_end_at":"2022-01-05 23:00:00",
"claim_condition":{
"and":[
{
"===":[
"female",
{
"var":"gender"
}
]
}
]
},
"is_reclaimable":null,
"notify_schedule_offset":null,
"notify_issue_offset_days":null,
"notify_issue_offset_hour":null,
"notify_remind_offset_days":null,
"notify_remind_offset_hour":null,
"notify_extend_offset_days":null,
"notify_extend_offset_hour":null,
"remind_target_id":null,
"extend_target_id":null,
"issue_target_id":null,
"end_at":null,
"total_allocations":null
}
Claim conditions
Claim conditions provide profile validation.
The profile must pass the defined validation to be eligible to claim the benefit.
If the profile fails validation, the customer will not see the claim as a valid option.
In this example, the profile must have a gender attribute of female, if this is not true, they cannot claim the benefit.
For this claim to be claimable against a profile, it must meet the below criteria.
if you've modified the above fields for your use, this criteria may change
gender must be female
is_published must be true
is_assignable must be true
profile has not exceeded max_redemptions
benefit has not exceeded max_global_redemptions
claim_period_start_at must be in the past
claim_period_end_at must be in the future
Claim timeframe
In claimable Configuration, there is a new JSON block called CALIM TIMEFRAME, which stores logic for time slot, the structure will be like below
{
"disable":{boolean}, //Optional
"timezone":"Europe/Copenhagen", //Mandatory
"timeframe":{ //Mandatory
"repeat":[
{
"start":"HH:MM",
"end":"HH:MM"
}
],
//Or
"custom":{
"Monday":[
{
"start":"HH:MM",
"end":"HH:MM"
},
{
"start":"HH:MM",
"end":"HH:MM"
}
]
}
}
}
-
If leave json block empty, it won’t check timeframe.
-
disable is optional, if it is true, it won’t check timeframe. This will help if you want to disable time frame check without deleting the configs so you can enable it again later
-
timezone and timeframe are mandatory, it one of them is missing, the benefit won’t be shown in claimable benefits.
-
repeat means everyday, for example, you have same time slot setting from Monday to Sunday, then you can use repeat
-
custom means specific days, for example, you have different time slot for Monday to Friday and Weekend . If repeat is in configs, it will ignore custom configs. Normally you should either repeat or custom.
-
You can have multi time frame for each day or everyday, Day must has Capital letter for the fist letter, like Monday, Tuesday. For example, two time slots for Monday below
"Monday":[
{
"start":"10:00",
"end":"14:00"
},
{
"start":"15:00",
"end":"18:00"
}
]
Below are a full example of custom timeframe settings
{
"disable":false,
"timezone":"Europe/Copenhagen",
"timeframe":{
"custom":{
"Monday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Tuesday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Wednesday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Thursday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Friday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Staturday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
],
"Sunday":[
{
"start":"10:00",
"end":"15:00"
},
{
"start":"16:00",
"end":"20:00"
}
]
}
}
}
Display a profiles available benefits.
It is important to be able to display a customer's available benefits.
In Omneo, benefits are sorted between claimable and issued benefits.
A claimable benefit is eligible for claim by the customer, and an issued benefit has been issued to the account and is available for use.
Displaying issued benefits
Using API Endpoint: Browse Profile Benefits
Using the Profile Benefits endpoint, list all issued benefits.
Displaying claimable benefits
Using API Endpoint: Browse Profile Claimable Benefits
Using the Profile Claimable Benefits endpoint, list all claimable benefits
You may wish to combine both claimable and issued benefit responses to be presented together on your site. Both types of benefits are available for use by the customer, with the claimable benefits requiring the extra step of claiming the reward and issuing it to the profile.
Filtering available benefits
In some instances, you may not wish to display all available benefits on your eCommerce platform.
instead of filtering these out on your frontend, Omneo allows additional parameters to be passed to the above endpoints to further filter the returned data.
Filtering Examples
In the example above, the tags contain "demo"
Let's imagine we only want to display benefits with the tag "demo"
We can append filter parameters to our original endpoint as below:
{{baseUrl}}/profiles/{profileId}/benefits?tags[]=demo
where ?tags[]=demo results in the API returning only eligible benefits, with a tag of "demo"
We can even go one step further an add more advanced filters to identify specific attributes such as:
?filter[benefit_definition_id]=3
A full list of filterable attributes can be found here
Claiming Benefits
Using API Endpoint: Add Benefit Claim
To claim a benefit, use the /benefits/claim endpoint and specify the handle of your definition and a valid timezone in your payload.
This will claim an instance of the benefit against the profile specified in the request URL.
Claiming a benefit issues an instance of the benefit against the profile, but does not redeem it.
An example payload might be:
{
"definition": "10offdemo",
"timezone": "Australia/Melbourne"
}
Claim-Redeeming benefits
Using API Endpoint: Add and Redeem Benefit Claim
Omneo provides a way to instantly claim and redeem a benefit in one go. This can be useful if your configured benefits require instant activation at the time of the claim. This eliminates the need for another API call at a later time.
providing the exact same payload as above. If you examine the profile after this action, you will notice an instance of the benefit has been issued to the profile, and the redemptions have been deducted from the benefit.
Redeeming a Benefit
Using API Endpoint: Add Benefit Redemption
When a customer claims a benefit, they may not necessarily use it until a later date.
Provide the profile id and benefit id in the request URL.
Don't confuse the benefit id with the benefit definition id. In this case, we need the benefit id which is the unique id of the benefit issued to the profile
This will check for available benefits issues against the profile, and redeem any that match the definition ID specified in the request.
Once examining the profile after a redemption, you will notice the issued benefits redemptions have been deducted. If no redeemable benefits are remaining you will receipt a 400 bad request in response.
Updating a Benefit
Using API Endpoint: Update a profile Benefit
Updating a benefit is usually only required when a modification to the expiry_date is required.
This is the preferred alternative to removing a benefit from a Profile. Changing the expiry_date to the past inactivates the benefit, whilst keeping all benefit records against the profile. If the benefit has already been communicated to the customer, this can also avoid confusion.
Removing a Benefit
Using API Endpoint: Delete Benefit
If you need to remove a benefit from an account you can do so by using the /benefits endpoint
this action will remove the benefit assigned to the profile even if it has already been redeemed.
Specify the profileID and benefitID in the request URL, and DELETE using the Omneo API
Deleting Benefits
We do not recommend deleting benefits from a profile. This will remove all record of the benefit being issued to the profile. If the benefit has been communicated to the customer, this could cause an issue.
Instead, change the
expiry_dateto a date in the past, using the Update a profile Benefit API endpoint. (See Updating a Benefit for details)
Conclusion
The methods described above allow developers to create, browse, claim, redeem and delete Omneo benefits. The Omneo API can be called from an eCommerce application, to obtain the data mentioned in this document.
If this is your first interaction with the Omneo API, review the Authentication documentation to get started.
Updated over 2 years ago