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 /v2/loyalties/examine/earning-rules

cURL

SPECIFIC_mode_order_paid

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"
      }
    }
  }
}
'

200

{
  "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"
              }
            }
          ]
        }
      ]
    }
  ]
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

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

200

application/json

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