Creating a Benefit Definition

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

Field	Description
`handle`	A unique URL-safe identifier. Used for lookups and deduplication.
`period`	Number of days the benefit is valid after issue.
`max_redemptions`	How many times the benefit can be redeemed. Set to `1` for single-use.
`is_claimable`	Whether the benefit appears in the claimable benefits list for profiles to self-select.
`is_published`	Whether 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"
  }'

Creating a Reward Definition Requesting Benefits

⌘I

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Creating a Benefit Definition

Create a benefit definition

Key fields

Make a benefit claimable

Issue a benefit to a profile

​Create a benefit definition

​Key fields

​Make a benefit claimable

​Issue a benefit to a profile

​Related

Create a benefit definition

Key fields

Make a benefit claimable

Issue a benefit to a profile

Related