Skip to main content
A Benefit Definition is the configuration for a non-monetary entitlement, free shipping, VIP access, event invitations, discount vouchers, or any non-dollar incentive. You create the definition once, then issue benefit instances to profiles or make it claimable.

​
Create a benefit definition

curl -X POST https://api.[tenant].getomneo.com/api/v3/benefit-definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Free Alterations",
    "handle": "free-alterations",
    "description": "Complimentary alterations for Gold and Platinum members.",
    "short_description": "Free alterations on any full-price item.",
    "long_description": "<p>Present this benefit in store when purchasing a full-price garment.</p>",
    "terms_conditions": "In-store only. Full-price items only. One per visit.",
    "earn_instructions": "Automatically issued when you reach Gold tier.",
    "redeem_instructions_store": "Show to staff when making a purchase.",
    "redeem_instructions_online": "Not available online.",
    "period": 365,
    "max_redemptions": 3,
    "is_claimable": false,
    "is_extendable": false,
    "is_reassignable": false,
    "is_published": true,
    "tags": ["gold", "platinum", "in-store"]
  }'

​
Key fields

FieldDescription
handleA unique URL-safe identifier. Used for lookups and deduplication.
periodNumber of days the benefit is valid after issue.
max_redemptionsHow many times the benefit can be redeemed. Set to 1 for single-use.
is_claimableWhether the benefit appears in the claimable benefits list for profiles to self-select.
is_publishedWhether the benefit is visible in customer-facing surfaces.
Note the id from the response, use it when issuing the benefit to a profile or configuring a Reaction.

​
Make a benefit claimable

Set is_claimable: true and optionally configure a claim_condition to control which profiles see the benefit in their claimable list. Profiles can then claim it themselves rather than having it issued automatically. 
{
  "is_claimable": true,
  "claim_condition": {
    "rule": "tier",
    "value": "gold"
  }
}

​
Issue a benefit to a profile

curl -X POST https://api.[tenant].getomneo.com/api/v3/benefits \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "benefit_definition_id": 94,
    "profile_id": "92a7996b-abb6-4c9c-a845-9aaf8202fab6",
    "issued_at": "2025-06-15 09:00:00",
    "timezone": "Australia/Melbourne"
  }'