Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omneo.io/llms.txt

Use this file to discover all available pages before exploring further.

Rewards are dollar-value discounts issued to a customer profile and redeemed at the point of sale or checkout. Working with rewards programmatically follows the same Definition/Issue/Redeem pattern as benefits.

​
Step 1: Create a Reward Definition

A Reward Definition describes the type of reward and its rules. Create once per reward type: 
curl -X POST https://api.[tenant].getomneo.com/api/v3/reward-definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Birthday Reward",
    "handle": "birthday-reward",
    "value": 10,
    "type": "birthday",
    "period": 30,
    "description": "Birthday reward valid for 30 days",
    "short_description": "$10 off for your birthday",
    "long_description": "<p>Enjoy $10 off your next purchase. Valid for 30 days.</p>",
    "terms_conditions": "Valid once per birthday period",
    "earn_instructions": "Automatically issued on your birthday",
    "is_assignable": true,
    "is_reassignable": false,
    "is_extendable": false,
    "tags": ["birthday"]
  }'
Note down the id.

​
Step 2: Issue a reward to a profile

curl -X POST https://api.[tenant].getomneo.com/api/v3/rewards \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "reward_definition_id": 6,
    "profile_id": "{profileId}",
    "value_initial": 10,
    "value_remaining": 10,
    "issued_at": "2025-06-15 00:00:00",
    "expires_at": "2025-07-15 23:59:59",
    "timezone": "Australia/Melbourne"
  }'

​
Checking a profile’s reward balance

GET /api/v3/profiles/{profileId}/balances
Response includes: 
{
  "data": {
    "reward_balance": 10,
    "point_balance": 0,
    "point_balance_dollars": 0,
    "combined_balance_dollars": 10
  }
}

​
Step 3: Redeem rewards

When a customer redeems at checkout, create a redemption specifying the strategy and amount: 
curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/redemptions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "strategies": ["rewards"],
    "amount": 10
  }'
Omneo deducts from rewards with the soonest expiry date first. Note the returned redemption id. 
curl -X POST https://api.[tenant].getomneo.com/api/v3/transactions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "{profileId}",
    "total": 89.95,
    "total_original": 99.95,
    "redemption_id": 158,
    "transacted_at": "2025-06-15 14:32:00",
    "external_id": "ORDER-10334",
    "items": [...]
  }'

​
Bulk importing rewards

For migrating historical reward balances from another system or issuing rewards to a large segment: 
POST /api/v3/rewards/batch
The batch endpoint accepts an array of reward objects in the same format as the single issue endpoint. For very large volumes, contact Omneo support to coordinate a managed import.

​
Checking rewards on a profile

GET /api/v3/profiles/{profileId}/rewards
Returns each individual reward with its definition, issued/expiry dates, initial value, and remaining value.