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

# Using Rates

> Configure Point Definition Rates to control how many points a profile earns per transaction.

**Point Definition Rates** define how many points a profile earns for a transaction. Each rate is linked to a [Point Definition](/api-reference/point-definition/overview) by its handle and can be scoped by location, region, country, time window, and JSON Logic conditions on the profile or product, allowing complex earn programs with minimal configuration.

## How rate resolution works

When a **Create Point** or **Create Tier Point** action runs with `check_rate = true`, Omneo resolves the applicable rate using this sequence:

1. Fetch all published, non-archived rates matching the Point Definition handle
2. Filter to rates whose time window is currently active (`start_time` ≤ now ≤ `end_time`)
3. Filter by location, region, and country: rates with no value set act as catch-alls
4. Evaluate `profile_conditions` against the profile (JSON Logic)
5. Evaluate `product_conditions` against the transaction or item (JSON Logic)
6. Rank remaining rates by specificity: more specific scoping wins
7. Break ties using `rate_priority` (`product` prefers rates with product conditions; `profile` prefers rates with profile conditions)
8. Apply the highest-ranked matching rate

Rate resolution is opt-in. It only runs when `check_rate = true` is set on the action.

## Point calculation

**Create Point:**

```
points = round(round(base_amount) × rate)
```

**Create Tier Point:**

```
points = round(base_amount × rate)
```

| Scenario                      | Base amount | Rate | Points earned    |
| ----------------------------- | ----------- | ---- | ---------------- |
| Standard earn                 | \$100       | 1.0  | 100              |
| Half earn                     | \$100       | 0.5  | 50               |
| Double earn                   | \$100       | 2.0  | 200              |
| No rate resolved (Tier Point) | \$100       | ,    | 100 (raw amount) |

If no rate resolves and no direct rate argument is provided, Create Point falls back to `rate = 1`. Create Tier Point falls back to the raw base amount.

## Specificity scoring

When multiple rates match, the rate with the highest specificity score wins. Each matched geographic field adds one point:

| Matched field   | Score |
| --------------- | ----- |
| `location_id`   | +1    |
| `region_id`     | +1    |
| `country_iso_2` | +1    |
| `code`          | +1    |

A rate scoped to a specific store outranks a catch-all rate with no geographic constraints.

## Pending period (issue period)

Use `issue_period` and `issue_period_type` on a rate to delay when points become spendable after they are earned. This is commonly used for returns windows, if a customer can return purchases within 30 days, you might issue points 31 days after the transaction.

| `issue_period_type` | Behaviour                                              |
| ------------------- | ------------------------------------------------------ |
| `hours`             | Active after N hours                                   |
| `days`              | Active after N days (end of day)                       |
| `weeks`             | Active after N weeks (end of day)                      |
| `months`            | Active after N months (end of day)                     |
| `years`             | Active after N years (end of day)                      |
| `absolute_date`     | Active on a fixed date set in `issue_absolute_expiry`  |
| `absolute_week`     | Active on the Nth weekday, N weeks from earn           |
| `absolute_month`    | Active on the Nth day of the month, N months from earn |

If no `accrued_at` is provided when the point is created, points are issued immediately regardless of the rate's issue period.

## Configuring a rate in CX Manager

### Prerequisites

* A Point Definition already exists with the handle you want to rate
* A Trigger Reaction uses a Create Point or Create Tier Point action referencing that definition, with `check_rate = true`

### Steps

<Steps>
  <Step title="Open Rates">
    In CX Manager, go to **Configuration → Rates** and select the **Point Definition** tab.
  </Step>

  <Step title="Add a rate">
    Select **Add rate** and complete the form.
  </Step>

  <Step title="Set the earn multiplier">
    Enter a **Rate** value. `1.0` = one point per dollar. `0.5` = half a point per dollar. `2.0` = double points.
  </Step>

  <Step title="Scope the rate (optional)">
    Set **Region**, **Country**, and/or **Location** to restrict when this rate applies. Leave blank to apply to all transactions.
  </Step>

  <Step title="Set a time window (optional)">
    Use **Start Time** and **End Time** to run a promotional rate for a fixed period.
  </Step>

  <Step title="Add conditions (optional)">
    Use **Profile Conditions** and **Product Conditions** to restrict the rate further using JSON Logic.
  </Step>

  <Step title="Publish">
    Toggle **Published** on, then save. The rate will not resolve until it is published.
  </Step>
</Steps>

## Condition examples

**Double points for Gold tier members only:**

```json theme={null}
{ "==": [{ "var": "tier.handle" }, "gold"] }
```

**Points only for a specific SKU:**

```json theme={null}
{ "==": [{ "var": "sku" }, "s100001"] }
```

Rates with no conditions apply unconditionally to all matching transactions.

## Testing rates

Use the [Estimating incentives](/dev-guides/incentives/estimating-incentives) guide to simulate transactions against your rate configuration before going live. This lets you verify specificity ordering and condition evaluation without creating real records.

## Related

* [Points](/concepts/incentives/points): conceptual overview of point types
* [Estimating incentives](/dev-guides/incentives/estimating-incentives): dry-run testing of earn rules
* [Rate API reference](/api-reference/rate/browse-rates): full rate endpoint specification
* [Point Definition API reference](/api-reference/point-definition/overview): managing definitions