Skip to main content
Benefits are non-monetary incentives issued to or claimed by customers. They represent specific entitlements, a percentage discount, a free product, an event RSVP, a competition entry, or a service entitlement.

​
Key characteristics

  • Benefits are profile-specific: they must be assigned to a known profile and cannot be applied generically
  • Benefits have an expiry date and a maximum redemption count
  • A benefit can be redeemed multiple times within its limits (e.g., 3 VIP lounge visits, unlimited 20% off knitwear until expiry)
  • Benefits are stand-alone: a single benefit is a single entitlement, not part of a balance
  • The main distinction from rewards: Benefits are percentage or product-based; Rewards are dollar-value

​
Issued vs claimed

Benefits have two distinct entry mechanics:
MechanicDescription
IssuedOmneo creates a benefit instance on a profile automatically (via reaction, tier attainment, etc.)
ClaimedThe customer requests the benefit themselves, Omneo checks eligibility via JSON conditions before granting
Claimable benefits allow customers to self-serve entitlements they qualify for, without requiring staff or an automation to issue them.

​
Benefit categories

​
Product discount

A percentage off specific products or categories:
  • “10% off all full-price items”
  • “15% off the denim category”

​
Free product (gift with purchase)

The benefit unlocks a 100% discount on a specified product, or enables “buy X get Y” or “gift with purchase” mechanics.

​
General entitlement

Service or access entitlements not directly tied to a product purchase:
  • Free alterations
  • Early access to sale
  • VIP lounge access
  • Event RSVP

​
How benefits work at POS/eCommerce

The promotional rules for benefits are configured in the POS or eCommerce system independently of how the customer earns the benefit. Once a benefit is issued to a profile, the promotional rule becomes unlocked via the Omneo integration when the customer is identified at purchase.

​
Benefit definition visibility

The GET /v3/profiles/{profile}/benefits/visibility endpoint returns the Benefit Definitions a profile is currently eligible to see. A definition is included only when all three conditions are met:
  1. The definition is published (is_published is true)
  2. The global redemption limit has not been reached (total_global_redemptions is less than max_global_redemptions, or no global limit is set)
  3. The definition’s visibility_condition evaluates to true for the profile
Use this endpoint to build UIs that surface which benefits a profile can claim or view.

​
Redemption conditions

For a benefit to be redeemable:
  1. The benefit’s redemption window must still be open (end date in the future)
  2. The benefit must be active (not expired)
  3. The benefit has not reached its maximum redemption count
  4. The benefit definition’s global redemption count has not been exceeded

​
Benefits and tiers

Benefits are commonly used in tier programs, higher tiers unlock access to premium benefits that lower-tier customers cannot access.

​
API

Benefits are created via Benefit Definitions, then issued as instances to profiles. The Profile Benefits API supports browsing, claiming, issuing, redeeming, and extending benefits.