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

# Creating a Reward Definition

> Setting up a Reward Definition via the API before issuing rewards to profiles.

A **Reward Definition** is the template that describes a type of reward, its name, dollar value, expiry period, and behaviour. You create one Reward Definition per reward type, then issue reward instances to profiles from it.

## Create a reward definition

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/rewards/definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Birthday Reward",
    "handle": "birthday-reward",
    "value": 20.00,
    "type": "birthday",
    "period": 30,
    "description": "A $20 birthday reward valid for 30 days.",
    "short_description": "$20 off your next purchase",
    "long_description": "<p>Happy birthday! Enjoy $20 off your next in-store or online purchase.</p>",
    "terms_conditions": "Single use. Cannot be combined with other offers.",
    "earn_instructions": "Automatically issued on your birthday.",
    "is_assignable": true,
    "is_extendable": true,
    "is_reassignable": false,
    "is_published": true,
    "tags": ["birthday", "member-benefit"]
  }'
```

### Key fields

| Field             | Description                                                                                                                                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `handle`          | A unique URL-safe identifier. Used for lookups and deduplication.                                                                                                                                                                          |
| `value`           | Dollar value of the reward.                                                                                                                                                                                                                |
| `type`            | Category of reward. Valid values: `activation`, `anniversary`, `birthday`, `bonus`, `campaign`, `customer-service`, `reactivation`, `spend`, `staff`, `system-adjustment`, `tier`, `achievement`, `status`, `points`, `referral`, `other`. |
| `period`          | Number of days the reward is valid after issue.                                                                                                                                                                                            |
| `is_assignable`   | Whether Omneo can automatically issue this reward via a Reaction.                                                                                                                                                                          |
| `is_extendable`   | Whether the expiry date can be extended after issue.                                                                                                                                                                                       |
| `is_reassignable` | Whether the reward can be moved to a different profile.                                                                                                                                                                                    |
| `is_published`    | Whether the reward is visible in customer-facing surfaces.                                                                                                                                                                                 |

The response includes the `id` of the new Reward Definition. Note this down, you will need it to issue rewards or configure Reactions.

## Issue a reward to a profile

Once the definition exists, create an instance for a specific profile:

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/rewards \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "reward_definition_id": 12,
    "profile_id": "92a7996b-abb6-4c9c-a845-9aaf8202fab6",
    "issued_at": "2025-06-15 09:00:00",
    "timezone": "Australia/Melbourne"
  }'
```

## Related

* [Working with benefits](/dev-guides/incentives/working-with-benefits)
* [Rewards concept](/concepts/incentives/rewards)
* [Reward definitions API](/api-reference/reward-definition/browse-reward-definitions)