> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # 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) ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/examine/earning-rules openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete API documentation for Voucherify Loyalty v2 system. Requires LOYALTY_V2 feature flag. servers: - url: https://api.voucherify.io description: Production security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - name: Card Definitions description: >- CRUD operations, lifecycle management, and activity history for card definitions. Card definitions describe the configuration for loyalty cards, including code generation, points expiration, earning/spending limits, pending points, refunds, and balance settings. - name: Programs description: >- Loyalty program CRUD, lifecycle management, program-scoped resource assignments (card definitions, earning rules, rewards, tier structures), member management (create, list, get, activate, deactivate, delete), card operations (points adjustment, pending points, expiring points, transactions), reward purchases, and activity history. - name: Earning Rules description: >- Manage earning rules that define how customers earn points or receive incentives based on triggers (events, segments, custom events). Includes CRUD, lifecycle, and activity history. - name: Tier Structures description: >- CRUD operations, lifecycle management, and activity history for tier structures. Includes nested tier definitions (create, list, update, delete) within tier structures. Tier structures define the tiering model for loyalty programs — how members qualify for and move between tiers. - name: Incentives description: >- Manage incentive definitions (fixed points, proportional points, material, digital). Includes CRUD, lifecycle transitions, and activity history. - name: Rewards description: >- CRUD, lifecycle operations, and activity history for reward definitions. Rewards can be material (product/SKU) or digital (discount coupons, gift vouchers). - name: Examine description: Examines the earning of loyalty points for a loyalty program member. paths: /v2/loyalties/examine/earning-rules: post: tags: - Examine summary: Examine Earnings description: >+ ⚠️ **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) operationId: examineLoyaltyEarnings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoyaltiesExamineEarningRulesRequestBody' examples: SPECIFIC_mode_order_paid: summary: 'SPECIFIC mode: Order Paid' description: >- Evaluates earning rules for a single order-paid trigger with order context. value: 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 SPECIFIC_mode_segment_entered: summary: 'SPECIFIC mode: Segment Entered' description: Evaluates earning rules for segment-entered trigger. value: trigger: type: SPECIFIC specific: event: customer.segment.entered customer_identification: type: member_id member_id: mlm_xyz789 customer_segment_entered: customer: metadata: is_premium: 'true' loyalty_score: 10 SPECIFIC_mode_custom_event: summary: 'SPECIFIC mode: Custom Event (SPECIFIC sub-mode)' description: Evaluates earning rules for a specific custom event schema. value: trigger: type: SPECIFIC specific: event: customer.custom_event customer_identification: type: customer_source_id customer_source_id: user_42 customer_custom_event: type: SPECIFIC specific: schema_id: ces_abc123 customer: metadata: plan: pro custom_event: metadata: source: mobile score: 50 ALL_mode_full_payload: summary: 'ALL mode: Full Payload' description: >- Evaluates all earning rules across all trigger types with independent metadata per event. Each event block provides its own customer metadata overlay. value: trigger: type: ALL customer_identification: type: customer_id customer_id: cust_abc123 customer_order_paid: customer: metadata: tier: gold order: amount: 4000 items: - amount: 4000 quantity: 1 metadata: channel: web customer_segment_entered: customer: metadata: is_premium: 'true' loyalty_score: 10 tier: gold customer_custom_event: type: ALL all: customer: metadata: plan: pro custom_event: metadata: source: mobile channel: web score: 60 ALL_mode_minimal: summary: 'ALL mode: Minimal (no event blocks)' description: >- Evaluates all earning rules but returns zero estimations without event context. value: trigger: type: ALL customer_identification: type: customer_id customer_id: cust_abc123 responses: '200': description: Successful dry-run estimation. content: application/json: schema: $ref: '#/components/schemas/LoyaltiesExamineEarningRulesResponseBody' examples: Earning rule dry-run estimation: value: 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 '400': description: Invalid payload (e.g., mutual exclusivity violation). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Customer or member not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: LoyaltiesExamineEarningRulesRequestBody: type: object required: - trigger - customer_identification properties: trigger: $ref: '#/components/schemas/VLExamineTrigger' customer_identification: $ref: '#/components/schemas/VLExamineCustomerIdentification' customer_order_paid: $ref: '#/components/schemas/VLExamineCustomerOrderPaid' description: >- 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. customer_segment_entered: $ref: '#/components/schemas/VLExamineCustomerSegmentEntered' description: >- 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. customer_custom_event: $ref: '#/components/schemas/VLExamineCustomerCustomEvent' description: >- Event-specific payload for customer.custom_event. Required if trigger.type is SPECIFIC with event=customer.custom_event, or included in ALL mode. LoyaltiesExamineEarningRulesResponseBody: type: object properties: event: type: string description: Determines the type of the event that triggers the estimation enum: - customer.custom_event - customer.order.paid - customer.segment.entered object: type: string const: earnings_examine_result description: Identifies the object type. customer: $ref: '#/components/schemas/VLExamineCustomerReference' earning_rules: type: array description: Catalog of earning rules that contributed to the estimation. items: $ref: '#/components/schemas/VLExamineEarningRuleDetail' memberships: type: array description: List of earning opportunities per active membership. items: $ref: '#/components/schemas/VLExamineMemberEarningsOpportunity' ErrorResponse: type: object description: Standard error response. properties: code: type: integer description: HTTP status code. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional error details. request_id: type: - string - 'null' description: Request identifier for tracing. resource_id: type: string description: Related resource identifier (when applicable). resource_type: type: string description: Related resource type (when applicable). required: - code - key - message VLExamineTrigger: type: object description: Trigger configuration for examination. Discriminated union on `type`. required: - type properties: type: type: string enum: - ALL - SPECIFIC description: >- Trigger mode: ALL examines all earning rule triggers in a single call; SPECIFIC examines a single trigger event. specific: $ref: '#/components/schemas/VLExamineTriggerSpecific' description: >- Required when type is SPECIFIC. Specifies the single event to examine. VLExamineCustomerIdentification: type: object description: Discriminated union identifying who is being evaluated. required: - type properties: type: type: string enum: - customer_id - customer_source_id - member_id description: Determines which ID field is evaluated and required. customer_id: type: string description: Internal customer ID (cust_*). Evaluates all programs. customer_source_id: type: string description: External customer source ID. Evaluates all programs. member_id: type: string description: Internal member ID (mloy_*). Scopes to a single program. VLExamineCustomerOrderPaid: type: object description: >- Event-specific payload for customer.order.paid containing context for rule evaluation. properties: customer: type: object properties: metadata: type: object description: >- Customer metadata overlay (merged onto the resolved customer, not persisted). member: type: object description: >- Member metadata overlay. Only allowed when customer_identification.type is member_id. properties: metadata: type: object order: $ref: '#/components/schemas/VLExamineOrderParams' VLExamineCustomerSegmentEntered: type: object description: >- Event-specific payload for customer.segment.entered containing context for rule evaluation. properties: customer: type: object description: Customer context with optional metadata overlay. properties: metadata: type: object description: >- Customer metadata overlay (merged onto the resolved customer, not persisted). member: type: object description: >- Member metadata overlay. Only allowed when customer_identification.type is member_id. properties: metadata: type: object description: Member metadata overlay. VLExamineCustomerCustomEvent: type: object description: >- Event-specific payload for customer.custom_event. Supports both SPECIFIC (single schema) and ALL (all schemas) sub-modes. required: - type properties: type: type: string enum: - ALL - SPECIFIC description: >- Custom event sub-mode: ALL matches all custom event schemas; SPECIFIC matches a single schema. all: $ref: '#/components/schemas/VLExamineCustomerCustomEventAll' description: >- Required when type is ALL. Provides context matched against all custom event schemas. specific: $ref: '#/components/schemas/VLExamineCustomerCustomEventSpecific' description: >- Required when type is SPECIFIC. Provides context for a single custom event schema. VLExamineCustomerReference: type: object description: Customer reference in examine response. properties: id: type: string description: Customer unique identifier assigned by Voucherify (cust_*). source_id: type: string description: Customer external source identifier. metadata: type: object description: Customer metadata. object: type: string const: customer description: Identifies the object type. VLExamineEarningRuleDetail: type: object description: Earning rule detail in examine response catalog. properties: id: type: string description: Earning rule unique identifier assigned by Voucherify. name: type: string description: Earning rule name. metadata: type: object description: Earning rule metadata. object: type: string const: earning_rule description: Identifies the object type. VLExamineMemberEarningsOpportunity: type: object properties: object: type: string const: member_earnings_opportunity description: Identifies the object type. member: $ref: '#/components/schemas/VLExamineMemberReference' program: $ref: '#/components/schemas/VLExamineProgramReference' cards: type: array description: Per-card point estimations with earning rule breakdowns. items: $ref: '#/components/schemas/VLExamineCardEstimation' incentives: type: array description: >- Fulfillable incentives (digital, material) with linked earning rules. items: $ref: '#/components/schemas/VLExamineIncentiveEstimation' VLExamineTriggerSpecific: type: object description: Specific trigger event selection. required: - event properties: event: type: string enum: - customer.order.paid - customer.segment.entered - customer.custom_event description: Trigger event to examine. VLExamineOrderParams: type: object properties: amount: type: integer description: Post-discount order amount (cents). initial_amount: type: integer description: Pre-discount order amount (cents). discount_amount: type: integer description: Total discount amount (cents). metadata: type: object description: Order metadata for rule evaluation. items: type: array items: $ref: '#/components/schemas/VLExamineOrderItemParams' VLExamineCustomerCustomEventAll: type: object description: >- Custom event payload for ALL sub-mode (matches all custom event schemas). properties: customer: type: object description: Customer context with optional metadata overlay. properties: metadata: type: object description: >- Customer metadata overlay (merged onto the resolved customer, not persisted). custom_event: type: object description: Custom event metadata for matching against all schemas. properties: metadata: type: object description: Custom event metadata. VLExamineCustomerCustomEventSpecific: type: object description: Custom event payload for SPECIFIC sub-mode (single schema). required: - schema_id properties: schema_id: type: string description: Custom event schema identifier (ces_*). customer: type: object description: Customer context with optional metadata overlay. properties: metadata: type: object description: Customer metadata overlay. custom_event: type: object description: Custom event data matching the specified schema. properties: metadata: type: object description: Custom event metadata. VLExamineMemberReference: type: object description: Lightweight member reference in examine response. properties: id: type: string description: Member unique identifier assigned by Voucherify. customer_id: type: string description: Customer unique identifier assigned by Voucherify (cust_*). program_id: type: string description: Program unique identifier assigned by Voucherify. metadata: type: object description: Member metadata. object: type: string const: member description: Identifies the object type. VLExamineProgramReference: type: object description: Lightweight program reference in examine response. properties: id: type: string description: Program unique identifier assigned by Voucherify. name: type: string description: Program name. metadata: type: object description: Program metadata. object: type: string const: program description: Identifies the object type. VLExamineCardEstimation: type: object properties: object: type: string const: card_estimation description: Identifies the object type. card: $ref: '#/components/schemas/VLExamineCardReference' points_estimation: type: integer description: >- Total estimated points for this card (fixed + proportional + incentive points combined). Equals the sum of nested earning_rules[].points_estimation. earning_rules: type: array description: Per-earning-rule point breakdown for this card. items: $ref: '#/components/schemas/VLExamineEarningRuleEstimation' VLExamineIncentiveEstimation: type: object description: Incentive estimation with linked earning rules. properties: object: type: string const: incentive_estimation description: Identifies the object type. incentive: $ref: '#/components/schemas/VLExamineIncentiveReference' earning_rules: type: array description: Earning rules linked to this incentive. items: type: object properties: object: type: string const: earning_rule_estimation description: Identifies the object type. earning_rule: $ref: '#/components/schemas/VLExamineEarningRuleReference' VLExamineOrderItemParams: type: object properties: id: type: string source_id: type: string product_id: type: string sku_id: type: string related_object: type: string enum: - product - sku amount: type: integer discount_amount: type: integer quantity: type: integer price: type: integer product: type: object properties: id: type: string source_id: type: string price: type: integer sku: type: object properties: id: type: string source_id: type: string price: type: integer metadata: type: object VLExamineCardReference: type: object description: Card reference in examine response. properties: id: type: string description: Card unique identifier assigned by Voucherify. card_definition_id: type: string description: Card definition unique identifier assigned by Voucherify. card_type: type: string description: Card type (e.g., INDIVIDUAL, BULK). code: type: string description: Card code. object: type: string const: card description: Identifies the object type. VLExamineEarningRuleEstimation: type: object description: Per-earning-rule estimation with points breakdown. properties: object: type: string const: earning_rule_estimation description: Identifies the object type. earning_rule: $ref: '#/components/schemas/VLExamineEarningRuleReference' points_estimation: type: integer description: Estimated points for this earning rule. VLExamineIncentiveReference: type: object description: Incentive reference in examine response. properties: id: type: string description: Incentive unique identifier assigned by Voucherify. name: type: string description: Incentive name. type: type: string enum: - DIGITAL - MATERIAL - POINTS - POINTS_PROPORTIONAL description: Incentive type. object: type: string const: incentive description: Identifies the object type. VLExamineEarningRuleReference: type: object description: Earning rule reference in examine response. properties: id: type: string description: Earning rule unique identifier assigned by Voucherify. object: type: string const: earning_rule description: Identifies the object type. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````