curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/examine/earning-rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "trigger": {
    "type": "SPECIFIC",
    "specific": {
      "event": "customer.order.paid"
    }
  },
  "customer_identification": {
    "type": "customer_id",
    "customer_id": "cust_abc123"
  },
  "customer_order_paid": {
    "customer": {
      "metadata": {
        "tier": "gold"
      }
    },
    "order": {
      "amount": 5000,
      "items": [
        {
          "amount": 5000,
          "quantity": 1,
          "product_id": "prod_001",
          "metadata": {
            "category": "electronics"
          }
        }
      ],
      "metadata": {
        "channel": "web"
      }
    }
  }
}
'

{
  "event": "customer.order.paid",
  "object": "earnings_examine_result",
  "customer": {
    "id": "cust_01HXXXXXXXXXXXX",
    "source_id": "user-source-001",
    "metadata": {},
    "object": "customer"
  },
  "earning_rules": [
    {
      "id": "leru_01HXXXXXXXXXXXX01",
      "name": "ER Inline Points + Incentive Points",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "leru_01HXXXXXXXXXXXX02",
      "name": "ER Inline Proportional + Incentive Proportional",
      "metadata": {},
      "object": "earning_rule"
    }
  ],
  "memberships": [
    {
      "object": "member_earnings_opportunity",
      "member": {
        "id": "lmbr_01HXXXXXXXXXXXX",
        "customer_id": "cust_01HXXXXXXXXXXXX",
        "program_id": "lprg_01HXXXXXXXXXXXX",
        "metadata": {},
        "object": "member"
      },
      "program": {
        "id": "lprg_01HXXXXXXXXXXXX",
        "name": "Summer Loyalty Program",
        "metadata": {},
        "object": "program"
      },
      "cards": [
        {
          "object": "card_estimation",
          "card": {
            "id": "lcrd_01HXXXXXXXXXXXX01",
            "card_definition_id": "lcdef_01HXXXXXXXXXXXX01",
            "card_type": "INDIVIDUAL",
            "code": "ABC12345",
            "object": "card"
          },
          "points_estimation": 225,
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              },
              "points_estimation": 150
            },
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              },
              "points_estimation": 75
            }
          ]
        },
        {
          "object": "card_estimation",
          "card": {
            "id": "lcrd_01HXXXXXXXXXXXX02",
            "card_definition_id": "lcdef_01HXXXXXXXXXXXX02",
            "card_type": "INDIVIDUAL",
            "code": "XYZ67890",
            "object": "card"
          },
          "points_estimation": 300,
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              },
              "points_estimation": 100
            },
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              },
              "points_estimation": 200
            }
          ]
        }
      ],
      "incentives": [
        {
          "object": "incentive_estimation",
          "incentive": {
            "id": "linc_01HXXXXXXXXXXXX01",
            "name": "Incentive Digital",
            "type": "DIGITAL",
            "object": "incentive"
          },
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              }
            }
          ]
        },
        {
          "object": "incentive_estimation",
          "incentive": {
            "id": "linc_01HXXXXXXXXXXXX02",
            "name": "Incentive Material",
            "type": "MATERIAL",
            "object": "incentive"
          },
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              }
            }
          ]
        }
      ]
    }
  ]
}

Examine Earnings

⚠️ BETA endpoint

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager.

Performs a dry-run estimation of points and incentives a customer (or member) would earn based on trigger events, without actually triggering any earning rule processing or modifying balances.

Trigger Modes

SPECIFIC: Evaluates earning rules for a single trigger event type (order paid, segment entered, or custom event). Provide the corresponding event block with context.
ALL: Evaluates all active earning rules across all trigger types in a single call. Each event block carries independent metadata context, enabling multi-scenario what-if analysis.

Request Structure

trigger.type: “SPECIFIC” or “ALL”
trigger.specific.event (SPECIFIC mode): One of customer.order.paid, customer.segment.entered, customer.custom_event
customer_identification: Customer or member identifier
Event blocks (conditional): Provide the block(s) corresponding to the trigger(s) you want to evaluate:
- customer_order_paid: Context for order-paid trigger
- customer_segment_entered: Context for segment-entered trigger
- customer_custom_event: Context for custom-event trigger (with ALL/SPECIFIC sub-mode)

POST

loyalties

examine

earning-rules

curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/examine/earning-rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "trigger": {
    "type": "SPECIFIC",
    "specific": {
      "event": "customer.order.paid"
    }
  },
  "customer_identification": {
    "type": "customer_id",
    "customer_id": "cust_abc123"
  },
  "customer_order_paid": {
    "customer": {
      "metadata": {
        "tier": "gold"
      }
    },
    "order": {
      "amount": 5000,
      "items": [
        {
          "amount": 5000,
          "quantity": 1,
          "product_id": "prod_001",
          "metadata": {
            "category": "electronics"
          }
        }
      ],
      "metadata": {
        "channel": "web"
      }
    }
  }
}
'

{
  "event": "customer.order.paid",
  "object": "earnings_examine_result",
  "customer": {
    "id": "cust_01HXXXXXXXXXXXX",
    "source_id": "user-source-001",
    "metadata": {},
    "object": "customer"
  },
  "earning_rules": [
    {
      "id": "leru_01HXXXXXXXXXXXX01",
      "name": "ER Inline Points + Incentive Points",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "leru_01HXXXXXXXXXXXX02",
      "name": "ER Inline Proportional + Incentive Proportional",
      "metadata": {},
      "object": "earning_rule"
    }
  ],
  "memberships": [
    {
      "object": "member_earnings_opportunity",
      "member": {
        "id": "lmbr_01HXXXXXXXXXXXX",
        "customer_id": "cust_01HXXXXXXXXXXXX",
        "program_id": "lprg_01HXXXXXXXXXXXX",
        "metadata": {},
        "object": "member"
      },
      "program": {
        "id": "lprg_01HXXXXXXXXXXXX",
        "name": "Summer Loyalty Program",
        "metadata": {},
        "object": "program"
      },
      "cards": [
        {
          "object": "card_estimation",
          "card": {
            "id": "lcrd_01HXXXXXXXXXXXX01",
            "card_definition_id": "lcdef_01HXXXXXXXXXXXX01",
            "card_type": "INDIVIDUAL",
            "code": "ABC12345",
            "object": "card"
          },
          "points_estimation": 225,
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              },
              "points_estimation": 150
            },
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              },
              "points_estimation": 75
            }
          ]
        },
        {
          "object": "card_estimation",
          "card": {
            "id": "lcrd_01HXXXXXXXXXXXX02",
            "card_definition_id": "lcdef_01HXXXXXXXXXXXX02",
            "card_type": "INDIVIDUAL",
            "code": "XYZ67890",
            "object": "card"
          },
          "points_estimation": 300,
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              },
              "points_estimation": 100
            },
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              },
              "points_estimation": 200
            }
          ]
        }
      ],
      "incentives": [
        {
          "object": "incentive_estimation",
          "incentive": {
            "id": "linc_01HXXXXXXXXXXXX01",
            "name": "Incentive Digital",
            "type": "DIGITAL",
            "object": "incentive"
          },
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX01",
                "object": "earning_rule"
              }
            }
          ]
        },
        {
          "object": "incentive_estimation",
          "incentive": {
            "id": "linc_01HXXXXXXXXXXXX02",
            "name": "Incentive Material",
            "type": "MATERIAL",
            "object": "incentive"
          },
          "earning_rules": [
            {
              "object": "earning_rule_estimation",
              "earning_rule": {
                "id": "leru_01HXXXXXXXXXXXX02",
                "object": "earning_rule"
              }
            }
          ]
        }
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

trigger

object

required

Trigger configuration for examination. Discriminated union on type.

Show child attributes

customer_identification

object

required

Discriminated union identifying who is being evaluated.

Show child attributes

customer_order_paid

object

Event-specific payload for customer.order.paid. Required if trigger.type is SPECIFIC with event=customer.order.paid, or included in ALL mode to provide order context.

Show child attributes

customer_segment_entered

object

Event-specific payload for customer.segment.entered. Required if trigger.type is SPECIFIC with event=customer.segment.entered, or included in ALL mode to provide segment context.

Show child attributes

customer_custom_event

object

Event-specific payload for customer.custom_event. Required if trigger.type is SPECIFIC with event=customer.custom_event, or included in ALL mode.

Show child attributes

Response

Successful dry-run estimation.

event

enum<string>

Determines the type of the event that triggers the estimation

Available options:

customer.custom_event,

customer.order.paid,

customer.segment.entered

object

string

Identifies the object type.

Allowed value: "earnings_examine_result"

customer

object

Customer reference in examine response.

Show child attributes

earning_rules

object[]

Catalog of earning rules that contributed to the estimation.

Show child attributes

memberships

object[]

List of earning opportunities per active membership.

Show child attributes

Last modified on June 2, 2026

⌘I