> ## 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.

# List 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.

Lists earning rules with optional filtering, ordering, and cursor-based pagination.
Deleted earning rules are excluded.




## OpenAPI

````yaml /openapi/loyalties-v2.json get /v2/loyalties/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/earning-rules:
    get:
      tags:
        - Earning Rules
      summary: List 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.


        Lists earning rules with optional filtering, ordering, and cursor-based
        pagination.

        Deleted earning rules are excluded.
      operationId: listEarningRules
      parameters:
        - name: filters[junction]
          in: query
          schema:
            type: string
            enum:
              - AND
              - OR
          description: Logical junction for combining filter conditions.
        - name: filters[id][conditions][$is]
          in: query
          schema:
            type: string
          description: Filter by exact earning rule ID.
        - name: filters[id][conditions][$is_not]
          in: query
          schema:
            type: string
          description: Exclude earning rule by ID.
        - name: filters[id][conditions][$in]
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by earning rule IDs (up to 100).
        - name: filters[id][conditions][$not_in]
          in: query
          schema:
            type: array
            items:
              type: string
          description: Exclude earning rule IDs (up to 100).
        - name: filters[name][conditions][$is]
          in: query
          schema:
            type: string
          description: Filter by exact name.
        - name: filters[name][conditions][$contains]
          in: query
          schema:
            type: string
          description: Filter by name containing substring.
        - name: filters[name][conditions][$starts_with]
          in: query
          schema:
            type: string
          description: Filter by name starting with prefix.
        - name: filters[status][conditions][$is]
          in: query
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
              - DRAFT
          description: Filter by exact status.
        - name: filters[status][conditions][$in]
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - ACTIVE
                - INACTIVE
                - DRAFT
          description: Filter by statuses.
        - name: filters[created_at][conditions][$before]
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by creation date before.
        - name: filters[created_at][conditions][$after]
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by creation date after.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Maximum number of results to return.
        - name: order
          in: query
          schema:
            oneOf:
              - type: string
                enum:
                  - '-created_at'
                  - created_at
                  - name
                  - '-name'
              - type: array
                items:
                  type: string
                  enum:
                    - '-created_at'
                    - created_at
                    - name
                    - '-name'
          description: >-
            Sort order. Prefix with `-` for descending. Default is
            `-created_at`.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination (obtained from previous response).
      responses:
        '200':
          description: List of earning rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarningRuleListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    EarningRuleListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EarningRuleResponse'
        cursor:
          oneOf:
            - $ref: '#/components/schemas/PaginationCursor'
            - type: 'null'
        object:
          type: string
          const: list
      required:
        - data
        - object
    EarningRuleResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique earning rule identifier.
        name:
          type: string
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - INACTIVE
            - DELETED
        earnings:
          type: array
          items:
            $ref: '#/components/schemas/EarningRuleEarningDTO'
        trigger:
          $ref: '#/components/schemas/EarningRuleTriggerDTO'
        error:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleErrorDTO'
            - type: 'null'
        validity_hours:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleValidityHoursDTO'
            - type: 'null'
        start_date:
          type:
            - string
            - 'null'
          format: date-time
        end_date:
          type:
            - string
            - 'null'
          format: date-time
        trigger_limits:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleTriggerLimitsDTO'
            - type: 'null'
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        object:
          type: string
          const: earning_rule
      required:
        - id
        - name
        - status
        - earnings
        - trigger
        - metadata
        - created_at
        - object
    PaginationCursor:
      type: object
      description: Cursor for fetching the next page of results.
      properties:
        next:
          type: string
          description: >-
            Cursor token to pass as the `cursor` query parameter for the next
            page.
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this cursor expires.
      required:
        - next
        - expires_at
    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
    EarningRuleEarningDTO:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
        rules:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleRulesGroupDTO'
            - type: 'null'
        effects:
          type: array
          items:
            $ref: '#/components/schemas/EarningRuleEffectDTO'
        tier_rules:
          description: >-
            Defines earning rules based on member tiers. Has two modes: 

            - `NO_REQUIREMENTS`: Member doesn't have to belong to a tier
            structure to receive earnings.

            - `ANY_OF`: Member has to belong to a defined tier structure to
            receive earnings.
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEarningsType'
    EarningRuleTriggerDTO:
      type: object
      properties:
        event:
          type: string
          enum:
            - customer.order.paid
            - customer.custom_event
            - customer.segment.entered
        custom_event:
          oneOf:
            - type: object
              properties:
                schema_id:
                  type: string
            - type: 'null'
        segment:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
            - type: 'null'
    EarningRuleErrorDTO:
      type: object
      properties:
        message:
          type: string
    EarningRuleValidityHoursDTO:
      type: object
      properties:
        daily:
          type: array
          items:
            type: object
            properties:
              days_of_week:
                type: array
                items:
                  type: integer
              start_time:
                type: string
              end_time:
                type: string
    EarningRuleTriggerLimitsDTO:
      type: object
      properties:
        cooldown:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsCooldownDTO'
            - type: 'null'
        frequency:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsFrequencyDTO'
            - type: 'null'
    EarningRuleRulesGroupDTO:
      type: object
      properties:
        logic:
          type: string
      additionalProperties:
        $ref: '#/components/schemas/EarningRuleDefinitionDTO'
    EarningRuleEffectDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - POINTS
            - POINTS_PROPORTIONAL
            - INCENTIVE
        points:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectPointsDTO'
            - type: 'null'
        points_proportional:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectPointsProportionalDTO'
            - type: 'null'
        incentive:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectIncentiveDTO'
            - type: 'null'
    EarningRuleEarningsType:
      oneOf:
        - type: object
          title: No requirements
          properties:
            type:
              type: string
              description: >-
                Member doesn't have to belong to any tier structure to receive
                earnings.
              enum:
                - NO_REQUIREMENTS
          required:
            - type
        - type: object
          title: Any of
          properties:
            type:
              type: string
              description: Member has to belong to a tier structure to receive earnings.
              enum:
                - ANY_OF
            any_of:
              type: array
              description: >-
                Defines tier structures and tiers to which a member has to
                belong to receive earnings. The member has to belong to any of
                the defined tier structures or tiers.
              items:
                type: object
                properties:
                  tier_structure_id:
                    type: string
                    description: Unique tier structure identifier.
                  tier_ids:
                    type: array
                    description: Array of unique tier identifiers.
                    items:
                      type: string
                required:
                  - tier_structure_id
                  - tier_ids
          required:
            - type
            - any_of
    TriggerLimitsCooldownDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_COOLDOWN
            - FIXED_COOLDOWN
        fixed_cooldown:
          oneOf:
            - type: object
              properties:
                period:
                  type: object
                  properties:
                    value:
                      type: integer
                    unit:
                      type: string
                      enum:
                        - HOUR
                        - DAY
                        - WEEK
                        - MONTH
                        - YEAR
            - type: 'null'
    TriggerLimitsFrequencyDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          type: array
          items:
            $ref: '#/components/schemas/TriggerLimitsFrequencyLimitDTO'
    EarningRuleDefinitionDTO:
      type: object
      properties:
        name:
          type: string
        property:
          type:
            - string
            - 'null'
        conditions:
          type:
            - object
            - 'null'
          additionalProperties: true
        rules:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleRulesGroupDTO'
            - type: 'null'
        error:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleErrorDTO'
            - type: 'null'
        schema_id:
          type:
            - string
            - 'null'
    EarningRuleEffectPointsDTO:
      type: object
      properties:
        value:
          type: integer
        card_definition_id:
          type: string
        points_expiration:
          oneOf:
            - $ref: '#/components/schemas/PointsExpirationDTO'
            - type: 'null'
    EarningRuleEffectPointsProportionalDTO:
      type: object
      properties:
        calculation_type:
          type: string
          enum:
            - PRE_DISCOUNT_ORDER_AMOUNT
            - POST_DISCOUNT_ORDER_AMOUNT
            - PRE_DISCOUNT_ORDER_ITEMS_AMOUNT
            - POST_DISCOUNT_ORDER_ITEMS_AMOUNT
            - ORDER_ITEMS_QUANTITY
            - ORDER_METADATA_VALUE
            - CUSTOMER_METADATA_VALUE
        card_definition_id:
          type: string
        order:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalOrderDTO'
            - type: 'null'
        customer:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalCustomerDTO'
            - type: 'null'
        order_items:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalOrderItemsDTO'
            - type: 'null'
        points_expiration:
          oneOf:
            - $ref: '#/components/schemas/PointsExpirationDTO'
            - type: 'null'
    EarningRuleEffectIncentiveDTO:
      type: object
      properties:
        id:
          type: string
    TriggerLimitsFrequencyLimitDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - TIME_BASED
        period:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - CURRENT_PERIOD
                current_period:
                  oneOf:
                    - type: object
                      properties:
                        unit:
                          type: string
                          enum:
                            - DAY
                            - WEEK
                            - MONTH
                            - QUARTER
                            - YEAR
                    - type: 'null'
            - type: 'null'
        triggers:
          oneOf:
            - type: object
              properties:
                max:
                  type: integer
            - type: 'null'
    PointsExpirationDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_EXPIRATION
            - ROLLING_EXPIRATION
            - CALENDAR_EXPIRATION
            - SLIDING_EXPIRATION
        rolling_expiration:
          oneOf:
            - $ref: '#/components/schemas/RollingExpirationDTO'
            - type: 'null'
        calendar_expiration:
          oneOf:
            - $ref: '#/components/schemas/CalendarExpirationDTO'
            - type: 'null'
        sliding_expiration:
          oneOf:
            - $ref: '#/components/schemas/SlidingExpirationDTO'
            - type: 'null'
      required:
        - type
    PointsProportionalOrderDTO:
      type: object
      properties:
        amount:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalEveryDTO'
            - type: 'null'
        total_amount:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalEveryDTO'
            - type: 'null'
        metadata:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalMetadataDTO'
            - type: 'null'
    PointsProportionalCustomerDTO:
      type: object
      properties:
        metadata:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalMetadataDTO'
            - type: 'null'
    PointsProportionalOrderItemsDTO:
      type: object
      properties:
        amount:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalOrderItemsCalculationDTO'
            - type: 'null'
        subtotal_amount:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalOrderItemsCalculationDTO'
            - type: 'null'
        quantity:
          oneOf:
            - $ref: '#/components/schemas/PointsProportionalOrderItemsCalculationDTO'
            - type: 'null'
    RollingExpirationDTO:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/PeriodValueUnitDTO'
        rounding:
          oneOf:
            - $ref: '#/components/schemas/RollingRoundingDTO'
            - type: 'null'
      required:
        - period
    CalendarExpirationDTO:
      type: object
      properties:
        expiration_dates:
          type: array
          items:
            $ref: '#/components/schemas/DayMonthDTO'
      required:
        - expiration_dates
    SlidingExpirationDTO:
      type: object
      properties:
        earning_activity:
          type: boolean
        spending_activity:
          type: boolean
        custom_activity:
          type: boolean
        custom_activity_types:
          type: array
          items:
            type: string
          description: Custom event type IDs that reset the sliding window.
        period:
          $ref: '#/components/schemas/PeriodValueUnitDTO'
      required:
        - earning_activity
        - spending_activity
        - custom_activity
        - custom_activity_types
        - period
    PointsProportionalEveryDTO:
      type: object
      properties:
        every:
          type: integer
        value:
          type: integer
    PointsProportionalMetadataDTO:
      type: object
      properties:
        every:
          type: integer
        value:
          type: integer
        property:
          type: string
    PointsProportionalOrderItemsCalculationDTO:
      type: object
      properties:
        every:
          type: integer
        value:
          type: integer
        applicable_to:
          type: array
          items:
            $ref: '#/components/schemas/PointsProportionalApplicableToDTO'
    PeriodValueUnitDTO:
      type: object
      properties:
        value:
          type: integer
          minimum: 1
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
      required:
        - value
        - unit
    RollingRoundingDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - END_OF_MONTH
            - END_OF_QUARTER
            - END_OF_HALF_YEAR
            - END_OF_YEAR
            - END_OF_PARTICULAR_MONTH
        value:
          type:
            - integer
            - 'null'
          description: >-
            Required and between 1-12 when type is `END_OF_PARTICULAR_MONTH`.
            Must be null otherwise.
          minimum: 1
          maximum: 12
      required:
        - type
    DayMonthDTO:
      type: object
      properties:
        day:
          type: integer
          minimum: 1
          maximum: 31
        month:
          type: integer
          minimum: 1
          maximum: 12
      required:
        - day
        - month
    PointsProportionalApplicableToDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - product
            - sku
            - products_collection
        product:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
            - type: 'null'
        sku:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
            - type: 'null'
        products_collection:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
            - type: 'null'
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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

````