Working with Benefits

Benefits are non-monetary entitlements, they represent a status, access right, or experience rather than a dollar-value discount. Examples: free shipping, complimentary alterations, VIP access, first-spend discounts, member birthday experiences. Working with benefits involves up to four steps:

Create a Benefit Definition (once per benefit type)
Issue the benefit to a profile
Record a redemption when the benefit is used
Optionally link the redemption to a transaction

Step 1: Create a benefit definition

A Benefit Definition describes the type of benefit and its rules. You only need to create a definition once per benefit type.

curl -X POST https://api.[tenant].getomneo.com/api/v3/benefit-definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First Spend Discount",
    "handle": "first-spend",
    "description": "10% off first purchase for new members",
    "short_description": "Get 10% off your first spend with us!",
    "long_description": "<p>Valid for 7 days from issue date.</p>",
    "terms_conditions": "Terms and conditions apply",
    "earn_instructions": "Automatically issued on signup",
    "redeem_instructions_store": "Show to staff at checkout",
    "redeem_instructions_online": "Apply at checkout",
    "period": 7,
    "max_redemptions": 1,
    "is_extendable": false,
    "is_reassignable": false,
    "is_published": true,
    "tags": ["first-spend", "new-member"]
  }'

Note down the id from the response, you will need it to issue the benefit.

Step 2: 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"
  }'

Reading benefits on a profile

GET /api/v3/profiles/{profileId}/benefits

Returns all active benefits for the profile. Use this at POS or checkout to present the customer’s available benefits.

GET /api/v3/profiles/{profileId}/benefits/{benefitId}

Step 3: Record a redemption

When a customer uses a benefit, record the redemption:

curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/benefits/{benefitId}/redemptions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "issued_at": "2025-06-15 14:30:00",
    "timezone": "Australia/Melbourne",
    "external_id": "POS-REDEMPTION-001"
  }'

Note down the redemption id.

Step 4: Link the redemption to a transaction

When the redemption is tied to a purchase, include the redemption_id in the transaction payload:

curl -X POST https://api.[tenant].getomneo.com/api/v3/transactions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "92a7996b-abb6-4c9c-a845-9aaf8202fab6",
    "total": 89.99,
    "total_original": 99.99,
    "transacted_at": "2025-06-15 14:32:00",
    "timezone": "Australia/Melbourne",
    "redemption_id": 159,
    "items": [...]
  }'

Claimable benefits for eCommerce

For benefit redemption flows in eCommerce (rather than POS), see Claimable Benefits, eCommerce.

Working with Credits Claimable Benefits, eCommerce

⌘I

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Working with Benefits

Step 1: Create a benefit definition

Step 2: Issue a benefit to a profile

Reading benefits on a profile

Step 3: Record a redemption

Step 4: Link the redemption to a transaction

Claimable benefits for eCommerce

​Step 1: Create a benefit definition

​Step 2: Issue a benefit to a profile

​Reading benefits on a profile

​Step 3: Record a redemption

​Step 4: Link the redemption to a transaction

​Claimable benefits for eCommerce

Step 1: Create a benefit definition

Step 2: Issue a benefit to a profile

Reading benefits on a profile

Step 3: Record a redemption

Step 4: Link the redemption to a transaction

Claimable benefits for eCommerce