> ## 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 earning rules > ⚠️ **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. Estimates earning opportunities for a customer without triggering any actual earning. The `trigger` selects whether all trigger events or one specific event is examined. When a specific event is selected, exactly one matching context object is required: `customer_order_paid` for `customer.order.paid`, `customer_segment_entered` for `customer.segment.entered`, and `customer_custom_event` for `customer.custom_event` (the other context objects must not be present). ## 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 OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - 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: 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: 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: Benefits description: >- Manage benefit 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: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/examine/earning-rules: post: tags: - Examine summary: Examine earning rules 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. Estimates earning opportunities for a customer without triggering any actual earning. The `trigger` selects whether all trigger events or one specific event is examined. When a specific event is selected, exactly one matching context object is required: `customer_order_paid` for `customer.order.paid`, `customer_segment_entered` for `customer.segment.entered`, and `customer_custom_event` for `customer.custom_event` (the other context objects must not be present). operationId: examineEarningRules requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExamineEarningRulesRequest' responses: '200': description: Earning rules examination result content: application/json: schema: $ref: '#/components/schemas/ExamineEarningRulesResponse' '400': description: >- Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - e.g. duplicate resource or invalid state transition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ExamineEarningRulesRequest: type: object description: > Request body for examining earning rules. When `trigger.type` is `SPECIFIC`, the context object matching the specific event is required and the other context objects must not be present: `customer.order.paid` -> `customer_order_paid`, `customer.segment.entered` -> `customer_segment_entered`, `customer.custom_event` -> `customer_custom_event`. properties: trigger: $ref: '#/components/schemas/ExamineEarningRulesTrigger' customer_identification: $ref: '#/components/schemas/ExamineCustomerIdentification' customer_order_paid: $ref: '#/components/schemas/ExamineEarningRulesCustomerOrderPaid' customer_segment_entered: $ref: '#/components/schemas/ExamineEarningRulesCustomerSegmentEntered' customer_custom_event: $ref: '#/components/schemas/ExamineEarningRulesCustomerCustomEvent' required: - trigger - customer_identification additionalProperties: false allOf: - if: required: - trigger properties: trigger: properties: type: const: SPECIFIC specific: properties: event: const: customer.order.paid then: required: - customer_order_paid not: anyOf: - required: - customer_segment_entered - required: - customer_custom_event - if: required: - trigger properties: trigger: properties: type: const: SPECIFIC specific: properties: event: const: customer.segment.entered then: required: - customer_segment_entered not: anyOf: - required: - customer_order_paid - required: - customer_custom_event - if: required: - trigger properties: trigger: properties: type: const: SPECIFIC specific: properties: event: const: customer.custom_event then: required: - customer_custom_event not: anyOf: - required: - customer_order_paid - required: - customer_segment_entered ExamineEarningRulesResponse: type: object description: Earning rules examination result. properties: event: type: string description: > Examined trigger event (e.g. `customer.order.paid`, `customer.segment.entered`, `customer.custom_event`). customer: $ref: '#/components/schemas/ExamineCustomerReference' earning_rules: type: array description: All earning rules that matched during examination (deduplicated). items: $ref: '#/components/schemas/ExamineEarningRuleDetail' memberships: type: array description: Earning opportunities per program membership. items: $ref: '#/components/schemas/ExamineEarningRulesMembership' object: type: string const: earnings_examine_result description: Object type marker. Always `earnings_examine_result`. ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Identifier of the request that produced the error. ExamineEarningRulesTrigger: type: object description: > Which trigger events to examine. With `ALL`, all trigger events are examined and `specific` must be null/absent. With `SPECIFIC`, `specific` is required. properties: type: type: string enum: - ALL - SPECIFIC description: Trigger examination mode. specific: description: Specific event selection. Nullable. oneOf: - $ref: '#/components/schemas/ExamineEarningRulesTriggerSpecific' - type: 'null' additionalProperties: false allOf: - required: - type - if: properties: type: const: ALL then: properties: specific: type: 'null' - if: properties: type: const: SPECIFIC then: required: - specific properties: specific: $ref: '#/components/schemas/ExamineEarningRulesTriggerSpecific' ExamineCustomerIdentification: type: object description: > How the examined customer is identified. Depending on `type`, exactly one of `customer_id`, `customer_source_id` or `member_id` is required; the other two must not be present. properties: type: type: string enum: - customer_id - customer_source_id - member_id description: Identification method. customer_id: type: - string - 'null' pattern: ^cust_[a-zA-Z0-9]+ description: Customer ID (`cust_...`). Required when `type` is `customer_id`. customer_source_id: type: - string - number - 'null' description: > Customer source ID. May be provided as a string or a number. Required when `type` is `customer_source_id`. member_id: type: - string - 'null' pattern: ^lmbr_[a-f0-9]+$ description: Loyalty member ID (`lmbr_...`). Required when `type` is `member_id`. required: - type additionalProperties: false allOf: - if: required: - type properties: type: const: customer_id then: required: - customer_id not: anyOf: - required: - customer_source_id - required: - member_id - if: required: - type properties: type: const: customer_source_id then: required: - customer_source_id not: anyOf: - required: - customer_id - required: - member_id - if: required: - type properties: type: const: member_id then: required: - member_id not: anyOf: - required: - customer_id - required: - customer_source_id ExamineEarningRulesCustomerOrderPaid: type: object description: Context for examining `customer.order.paid` earning rules. properties: customer: $ref: '#/components/schemas/ExamineEarningRulesCustomer' member: $ref: '#/components/schemas/ExamineEarningRulesMember' order: $ref: '#/components/schemas/ExamineEarningRulesOrder' additionalProperties: false ExamineEarningRulesCustomerSegmentEntered: type: object description: Context for examining `customer.segment.entered` earning rules. properties: customer: $ref: '#/components/schemas/ExamineEarningRulesCustomer' member: $ref: '#/components/schemas/ExamineEarningRulesMember' additionalProperties: false ExamineEarningRulesCustomerCustomEvent: type: object description: > Context for examining `customer.custom_event` earning rules. With `type` = `ALL`, `all` is required and `specific` must be null/absent. With `SPECIFIC`, `specific` is required and `all` must be null/absent. properties: type: type: string enum: - ALL - SPECIFIC description: Whether to examine all custom events or one specific event. all: description: Context for all custom events. Nullable. oneOf: - $ref: '#/components/schemas/ExamineEarningRulesCustomerCustomEventAll' - type: 'null' specific: description: Context for a specific custom event. Nullable. oneOf: - $ref: >- #/components/schemas/ExamineEarningRulesCustomerCustomEventSpecific - type: 'null' additionalProperties: false allOf: - required: - type - if: properties: type: const: ALL then: required: - all properties: specific: type: 'null' - if: properties: type: const: SPECIFIC then: required: - specific properties: all: type: 'null' specific: $ref: >- #/components/schemas/ExamineEarningRulesCustomerCustomEventSpecific ExamineCustomerReference: type: object description: Customer reference in examine results. properties: id: type: string description: Customer ID (`cust_...`). source_id: type: string description: Customer source ID. metadata: type: object description: Customer metadata (empty object when unset). additionalProperties: true object: type: string const: customer description: Object type marker. Always `customer`. ExamineEarningRuleDetail: type: object description: Earning rule detail in examine results. properties: id: type: string description: Earning rule ID (`lern_...`). name: type: string description: Earning rule name. metadata: type: object description: Earning rule metadata (empty object when unset). additionalProperties: true object: type: string const: earning_rule description: Object type marker. Always `earning_rule`. ExamineEarningRulesMembership: type: object description: Earning opportunities for one program membership. properties: member: $ref: '#/components/schemas/ExamineMemberReference' program: $ref: '#/components/schemas/ExamineProgramReference' cards: type: array description: Points estimations per card. items: $ref: '#/components/schemas/ExamineEarningRulesCardEstimation' benefits: type: array description: Benefit estimations. items: $ref: '#/components/schemas/ExamineEarningRulesBenefitEstimation' object: type: string const: member_earnings_opportunity description: Object type marker. Always `member_earnings_opportunity`. ExamineEarningRulesTriggerSpecific: type: object description: Specific trigger event to examine. properties: event: type: string enum: - customer.order.paid - customer.segment.entered - customer.custom_event description: Trigger event. required: - event additionalProperties: false ExamineEarningRulesCustomer: type: object description: Customer metadata overrides used during examination. properties: metadata: description: Customer metadata overrides. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' additionalProperties: false ExamineEarningRulesMember: type: object description: Member metadata overrides used during examination. properties: metadata: description: Member metadata overrides. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' additionalProperties: false ExamineEarningRulesOrder: type: object description: A hypothetical order used for estimation. properties: amount: type: - string - number - 'null' description: > Order amount after discounts - a non-negative integer. May be provided as a string or a number. Nullable. initial_amount: type: - string - number - 'null' description: > Order amount before discounts - a non-negative integer. May be provided as a string or a number. Nullable. discount_amount: type: - string - number - 'null' description: > Total discount amount - a non-negative integer. May be provided as a string or a number. Nullable. items: type: - array - 'null' maxItems: 500 description: Order line items (up to 500). Nullable. items: $ref: '#/components/schemas/ExamineEarningRulesOrderItem' metadata: description: Order metadata. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' additionalProperties: false ExamineEarningRulesCustomerCustomEventAll: type: object description: Context for examining all custom events. properties: customer: $ref: '#/components/schemas/ExamineEarningRulesCustomer' member: $ref: '#/components/schemas/ExamineEarningRulesMember' custom_event: $ref: '#/components/schemas/ExamineEarningRulesCustomEventAll' additionalProperties: false ExamineEarningRulesCustomerCustomEventSpecific: type: object description: Context for examining a specific custom event. properties: customer: $ref: '#/components/schemas/ExamineEarningRulesCustomer' member: $ref: '#/components/schemas/ExamineEarningRulesMember' custom_event: $ref: '#/components/schemas/ExamineEarningRulesCustomEventSpecific' required: - custom_event additionalProperties: false ExamineMemberReference: type: object description: Member reference in examine results. properties: id: type: string description: Member ID (`lmbr_...`). customer_id: type: string description: Customer ID the member belongs to. program_id: type: string description: Program ID the member belongs to. metadata: type: object description: Member metadata (empty object when unset). additionalProperties: true object: type: string const: member description: Object type marker. Always `member`. ExamineProgramReference: type: object description: Program reference in examine results. properties: id: type: string description: Program ID (`lprg_...`). name: type: string description: Program name. metadata: type: object description: Program metadata (empty object when unset). additionalProperties: true object: type: string const: program description: Object type marker. Always `program`. ExamineEarningRulesCardEstimation: type: object description: Points estimation for a single card. properties: card: $ref: '#/components/schemas/ExamineCardReference' points_estimation: type: number description: Total estimated points for the card across matching earning rules. earning_rules: type: array description: Per-earning-rule estimations contributing to the total. items: $ref: '#/components/schemas/ExamineEarningRulesCardEarningRuleEstimation' object: type: string const: card_estimation description: Object type marker. Always `card_estimation`. ExamineEarningRulesBenefitEstimation: type: object description: Benefit estimation. properties: benefit: $ref: '#/components/schemas/ExamineBenefitReference' earning_rules: type: array description: Earning rules that would grant this benefit. items: $ref: >- #/components/schemas/ExamineEarningRulesBenefitEarningRuleEstimation object: type: string const: benefit_estimation description: Object type marker. Always `benefit_estimation`. EarningRuleMetadata: type: object description: Arbitrary key-value metadata; any JSON object is accepted. additionalProperties: true ExamineEarningRulesOrderItem: type: object description: A hypothetical order line item used for estimation. properties: id: type: - string - 'null' description: Order item ID. Nullable. source_id: type: - string - number - 'null' description: >- Order item source ID. May be provided as a string or a number. Nullable. product_id: type: - string - number - 'null' description: Product ID. May be provided as a string or a number. Nullable. sku_id: type: - string - number - 'null' description: SKU ID. May be provided as a string or a number. Nullable. related_object: description: Whether the item refers to a product or a SKU. Nullable. oneOf: - type: string enum: - product - sku - type: 'null' amount: type: - string - number - 'null' description: > Item amount before discounts - a non-negative integer. May be provided as a string or a number. Nullable. discount_amount: type: - string - number - 'null' description: > Item discount amount - a non-negative integer. May be provided as a string or a number. Nullable. quantity: type: - string - number - 'null' description: > Item quantity - a positive integer. May be provided as a string or a number. Nullable. price: type: - string - number - 'null' description: > Item unit price - a non-negative integer. May be provided as a string or a number. Nullable. product: description: Product details. Nullable. oneOf: - $ref: '#/components/schemas/ExamineEarningRulesOrderItemProduct' - type: 'null' sku: description: SKU details. Nullable. oneOf: - $ref: '#/components/schemas/ExamineEarningRulesOrderItemSku' - type: 'null' metadata: description: Order item metadata. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' additionalProperties: false ExamineEarningRulesCustomEventAll: type: object description: Metadata applied when examining all custom events. properties: metadata: description: Custom event metadata. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' additionalProperties: false ExamineEarningRulesCustomEventSpecific: type: object description: A specific custom event to examine. properties: schema_id: type: string pattern: ^ms_[a-zA-Z0-9]+ description: Custom event schema ID (`ms_...`). metadata: description: Custom event metadata. Nullable. oneOf: - $ref: '#/components/schemas/EarningRuleMetadata' - type: 'null' required: - schema_id additionalProperties: false ExamineCardReference: type: object description: Card reference in examine results. properties: id: type: string description: Card ID (`lcrd_...`). card_definition_id: type: string description: Card definition ID (`lcdef_...`). card_type: type: string enum: - INDIVIDUAL description: Card type. Currently only `INDIVIDUAL` exists. code: type: - string - 'null' description: > Card code. May be null right after member creation because card codes are generated asynchronously. object: type: string const: card description: Object type marker. Always `card`. ExamineEarningRulesCardEarningRuleEstimation: type: object description: Points estimation from a single earning rule for a card. properties: earning_rule: $ref: '#/components/schemas/ExamineEarningRuleReference' points_estimation: type: number description: Estimated points this earning rule would award to the card. object: type: string const: earning_rule_estimation description: Object type marker. Always `earning_rule_estimation`. ExamineBenefitReference: type: object description: Benefit reference in examine results. properties: id: type: string description: Benefit ID (`lben_...`). name: type: string description: Benefit name. type: type: string enum: - POINTS - POINTS_PROPORTIONAL - MATERIAL - DIGITAL description: Benefit type. object: type: string const: benefit description: Object type marker. Always `benefit`. ExamineEarningRulesBenefitEarningRuleEstimation: type: object description: Earning rule granting a benefit. properties: earning_rule: $ref: '#/components/schemas/ExamineEarningRuleReference' object: type: string const: earning_rule_estimation description: Object type marker. Always `earning_rule_estimation`. ExamineEarningRulesOrderItemProduct: type: object description: Product details for an examined order item. properties: id: type: - string - number - 'null' description: Product ID. May be provided as a string or a number. Nullable. source_id: type: - string - number - 'null' description: >- Product source ID. May be provided as a string or a number. Nullable. price: type: - string - number - 'null' description: > Product price - an integer amount of at most 9007199254740991. May be provided as a string or a number. Nullable. additionalProperties: false ExamineEarningRulesOrderItemSku: type: object description: SKU details for an examined order item. properties: id: type: - string - number - 'null' description: SKU ID. May be provided as a string or a number. Nullable. source_id: type: - string - number - 'null' description: SKU source ID. May be provided as a string or a number. Nullable. price: type: - string - number - 'null' description: > SKU price - an integer amount of at most 9007199254740991. May be provided as a string or a number. Nullable. additionalProperties: false ExamineEarningRuleReference: type: object description: Earning rule reference in examine results. properties: id: type: string description: Earning rule ID (`lern_...`). object: type: string const: earning_rule description: Object type marker. Always `earning_rule`. 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 ````