Estimating Incentives

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

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

{
  "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:

{
  "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:

[
  {
    "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.

Reactions overview: configuring the Trigger this endpoint simulates
Using Rates: how point definition rates are resolved
Creating transactions: submitting real transactions
API reference: full endpoint specification

Requesting Benefits Using Rates

⌘I

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Estimating Incentives

How it works

Prerequisites

Request

Example request

Response

Error handling

Common use cases

​How it works

​Prerequisites

​Request

​Example request

​Response

​Error handling

​Common use cases

​Related

How it works

Prerequisites

Request

Example request

Response

Error handling

Common use cases

Related