Skip to main content
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:
FieldRequiredDescription
trigger_idYesUUID of the Trigger Reaction to simulate
profile_idNoProfile to resolve earn rules against. Accepts email, card_pos, or other handle
location_idNoLocation used for rate scoping
totalYesTransaction total
transacted_atYesDatetime in YYYY-MM-DD HH:mm:ss format
timezoneNoDefaults to your client_timezone setting
itemsNoArray 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

StatusCause
404Trigger, profile, or location not found
422Validation 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.