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

# Estimating Incentives

> Simulate what incentives a transaction would earn before committing it to Omneo.

The incentive estimation endpoint lets you run a transaction through your configured Reactions in dry-run mode, returning what points and tier points would be awarded without creating any records. Use it at checkout to show customers their pending earn, or during integration testing to verify your earn rules are resolving correctly.

## How it works

Calling `POST /transactions/incentive-estimate` creates an in-memory transaction, loads the Trigger you specify, executes its actions in dry-run mode, and returns the results. Nothing is persisted.

The endpoint only executes actions that support dry-run: **Create Point**, **Create Points**, **Create Tier Point**, **Create Tier Points**, and **Create Point With Rate**.

## Prerequisites

* A published Trigger Reaction with event `transaction.created` or `transaction-item.created`
* At least one point-creating action configured on the trigger
* An API token with the `create-transactions` scope

## Request

```http theme={null}
POST /v3/transactions/incentive-estimate
Authorization: Bearer {token}
Content-Type: application/json
```

The request body mirrors a standard transaction payload. Required fields:

| Field           | Required | Description                                                                       |
| --------------- | -------- | --------------------------------------------------------------------------------- |
| `trigger_id`    | Yes      | UUID of the Trigger Reaction to simulate                                          |
| `profile_id`    | No       | Profile to resolve earn rules against. Accepts email, `card_pos`, or other handle |
| `location_id`   | No       | Location used for rate scoping                                                    |
| `total`         | Yes      | Transaction total                                                                 |
| `transacted_at` | Yes      | Datetime in `YYYY-MM-DD HH:mm:ss` format                                          |
| `timezone`      | No       | Defaults to your `client_timezone` setting                                        |
| `items`         | No       | Array of line items (required if trigger event is `transaction-item.created`)     |

Each item in `items` requires `name` and `price_sell`. Optional item fields: `sku`, `product_variant_sku`, `price_current`, `quantity` (negative for returns).

### Example request

```json theme={null}
{
  "trigger_id": "a1b2c3d4-...",
  "profile_id": "customer@example.com",
  "location_id": "loc_abc123",
  "total": 150.00,
  "transacted_at": "2026-05-07 10:00:00",
  "timezone": "Australia/Melbourne",
  "items": [
    {
      "name": "Linen Shirt",
      "price_sell": 89.95,
      "sku": "LS-001",
      "quantity": 1
    },
    {
      "name": "Cotton Tee",
      "price_sell": 59.95,
      "sku": "CT-002",
      "quantity": 1
    }
  ]
}
```

## Response

For `transaction.created` triggers, the response is a single object keyed by action UUID:

```json theme={null}
{
  "a1b2c3d4-action-uuid": {
    "points": 150,
    "point_definition_handle": "standard",
    "rate": 1.0
  }
}
```

For `transaction-item.created` triggers, the response is an array with one result per line item:

```json theme={null}
[
  {
    "action_uuid": "a1b2c3d4-action-uuid",
    "item_index": 0,
    "points": 90
  },
  {
    "action_uuid": "a1b2c3d4-action-uuid",
    "item_index": 1,
    "points": 60
  }
]
```

## Error handling

| Status | Cause                                         |
| ------ | --------------------------------------------- |
| `404`  | Trigger, profile, or location not found       |
| `422`  | Validation failure or missing required fields |

## Common use cases

**Show pending earn at checkout**: call the estimation endpoint when a cart is updated and display the projected point earn before the customer completes the purchase.

**Validate earn rules**: during integration testing, confirm that rate scoping (location, region, tier conditions) is resolving as expected before you submit real transactions.

**Preview promotional multipliers**: if you configure a time-limited double-points rate, use estimation to verify the multiplier is active before promoting it to customers.

## Related

* [Reactions overview](/dev-guides/reactions/overview): configuring the Trigger this endpoint simulates
* [Using Rates](/dev-guides/incentives/using-rates): how point definition rates are resolved
* [Creating transactions](/dev-guides/commerce/creating-transactions): submitting real transactions
* [API reference](/api-reference/transaction/estimate-incentives): full endpoint specification