> ## 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 Benefit Definition

> Setting up a Benefit Definition via the API before issuing or offering benefits to profiles.

A **Benefit Definition** is the configuration for a non-monetary entitlement, free shipping, VIP access, event invitations, discount vouchers, or any non-dollar incentive. You create the definition once, then issue benefit instances to profiles or make it claimable.

## Create a benefit definition

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/benefit-definitions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Free Alterations",
    "handle": "free-alterations",
    "description": "Complimentary alterations for Gold and Platinum members.",
    "short_description": "Free alterations on any full-price item.",
    "long_description": "<p>Present this benefit in store when purchasing a full-price garment.</p>",
    "terms_conditions": "In-store only. Full-price items only. One per visit.",
    "earn_instructions": "Automatically issued when you reach Gold tier.",
    "redeem_instructions_store": "Show to staff when making a purchase.",
    "redeem_instructions_online": "Not available online.",
    "period": 365,
    "max_redemptions": 3,
    "is_claimable": false,
    "is_extendable": false,
    "is_reassignable": false,
    "is_published": true,
    "tags": ["gold", "platinum", "in-store"]
  }'
```

### Key fields

| Field             | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `handle`          | A unique URL-safe identifier. Used for lookups and deduplication.                       |
| `period`          | Number of days the benefit is valid after issue.                                        |
| `max_redemptions` | How many times the benefit can be redeemed. Set to `1` for single-use.                  |
| `is_claimable`    | Whether the benefit appears in the claimable benefits list for profiles to self-select. |
| `is_published`    | Whether the benefit is visible in customer-facing surfaces.                             |

Note the `id` from the response, use it when issuing the benefit to a profile or configuring a Reaction.

## Make a benefit claimable

Set `is_claimable: true` and optionally configure a `claim_condition` to control which profiles see the benefit in their claimable list. Profiles can then claim it themselves rather than having it issued automatically.

```json theme={null}
{
  "is_claimable": true,
  "claim_condition": {
    "rule": "tier",
    "value": "gold"
  }
}
```

## Issue a benefit to a profile

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

## Related

* [Working with benefits](/dev-guides/incentives/working-with-benefits)
* [Requesting benefits](/dev-guides/incentives/requesting-benefits)
* [Benefits concept](/concepts/incentives/benefits)
* [Benefit definitions API](/api-reference/benefit-definition/browse-benefit-definitions)