> ## 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.

# POS Integration Guide

> Step-by-step API integration guide for connecting a Point of Sale system directly to Omneo.

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](/dev-guides/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)

```shell theme={null}
GET /api/v3/identities/search?handle=loyalty-card&identifier={cardNumber}
```

Returns the Omneo `profile_id`.

### By email or name (search)

```shell theme={null}
GET /api/v3/profiles?search={emailOrName}
```

### By Omneo profile ID (direct)

If your POS stores the Omneo profile ID in its customer database (recommended):

```shell theme={null}
GET /api/v3/profiles/{profileId}
```

## Step 2: Check the reward balance

```shell theme={null}
GET /api/v3/profiles/{profileId}/balances
```

```json theme={null}
{
  "data": {
    "reward_balance": 25.00,
    "point_balance": 1500,
    "point_balance_dollars": 15.00,
    "combined_balance_dollars": 40.00
  }
}
```

## Step 3: Check available benefits

```shell theme={null}
GET /api/v3/profiles/{profileId}/benefits?filter[status]=active
```

Returns active benefit instances the customer can redeem.

## Step 4: Create a redemption

### Redeem rewards

```shell theme={null}
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

```shell theme={null}
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`:

```shell theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
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 $50 reward on a $250 transaction:

| Line item | Original     | Reward share | Net          |
| --------- | ------------ | ------------ | ------------ |
| 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:

```shell theme={null}
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.