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.

This guide covers the full direct API integration flow for a POS system connecting to Omneo. For an overview of integration approaches, see POS Overview.

​
The checkout flow

  1. Customer presents at POS (card scan, membership number, or staff search)
  2. POS identifies the Omneo profile
  3. POS checks reward balance and available benefits
  4. Customer selects what to redeem
  5. POS creates a redemption
  6. POS completes the sale and records the transaction in Omneo

​
Step 1: Identify the customer

​
By loyalty card (identity lookup)

GET /api/v3/identities/search?handle=loyalty-card&identifier={cardNumber}
Returns the Omneo profile_id. 
GET /api/v3/profiles?search={emailOrName}

​
By Omneo profile ID (direct)

If your POS stores the Omneo profile ID in its customer database (recommended): 
GET /api/v3/profiles/{profileId}

​
Step 2: Check the reward balance

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

{
  "data": {
    "reward_balance": 25.00,
    "point_balance": 1500,
    "point_balance_dollars": 15.00,
    "combined_balance_dollars": 40.00
  }
}

​
Step 3: Check available benefits

GET /api/v3/profiles/{profileId}/benefits?filter[status]=active
Returns active benefit instances the customer can redeem.

​
Step 4: Create a redemption

​
Redeem rewards

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": 25.00
  }'
Note the redemption id from the response.

​
Redeem a benefit

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"
  }'

​
Step 5: Apply the redemption to a transaction

After payment is confirmed, record the transaction in Omneo with the 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": 175.00,
    "total_original": 200.00,
    "transacted_at": "2025-06-15 14:35:00",
    "timezone": "Australia/Melbourne",
    "receipt_ref": "659",
    "location_id": 2,
    "staff_id": 1993,
    "redemption_id": 158,
    "items": [...]
  }'

​
Reversing a redemption (payment failure)

If payment fails after a redemption has been created, reverse it within 10 minutes: 
POST /api/v3/profiles/{profileId}/redemptions/{redemptionId}/reverse
A reversal returns the reward or benefit to its original state with the same expiry and value.

​
Refunding a redemption (return/exchange)

For a post-sale return or exchange (not a failed payment), use a refund rather than a reversal. A refund creates a new incentive object: 
POST /api/v3/profiles/{profileId}/redemptions/{redemptionId}/refund

​
Applying reward value across line items

When a reward is redeemed, apply it proportionally across transaction line items. For a 50rewardona50 reward on a 250 transaction:
Line itemOriginalReward shareNet
Item 1$65.00$13.00$52.00
Item 2$115.00$23.00$92.00
Item 3$25.00$5.00$20.00
Item 4$45.00$9.00$36.00
Total$250.00$50.00$200.00

​
Staff management

Store staff records in Omneo and use staff_id in transaction payloads for attribution: 
POST /api/v3/staff
GET /api/v3/staff/{staffId}
PUT /api/v3/staff/{staffId}
DELETE /api/v3/staff/{staffId}

​
Syncing profiles to POS

Keep your POS customer database in sync with Omneo by subscribing to profile.created and profile.updated webhooks. When an Omneo profile changes, your webhook handler updates the corresponding record in the POS. Store the Omneo profile_id as an identity in the POS customer record for fast bidirectional lookup.