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

# Create Earning Rule

> ⚠️ **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.

Creates a new earning rule. The rule defines a trigger event, validation rules,
and effects (points or incentives) to award when triggered.

Requires `name`, `trigger`, and `earnings` (with at least one effect per earning).
Status defaults to `DRAFT` if not specified.




## OpenAPI

````yaml /openapi/loyalties-v2.json post /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:
    post:
      tags:
        - Earning Rules
      summary: Create Earning Rule
      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.


        Creates a new earning rule. The rule defines a trigger event, validation
        rules,

        and effects (points or incentives) to award when triggered.


        Requires `name`, `trigger`, and `earnings` (with at least one effect per
        earning).

        Status defaults to `DRAFT` if not specified.
      operationId: createEarningRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EarningRuleCreateRequest'
      responses:
        '200':
          description: Earning rule created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarningRuleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    EarningRuleCreateRequest:
      type: object
      required:
        - name
        - trigger
        - earnings
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Human-readable name for the earning rule.
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
          default: DRAFT
          description: Initial status. Defaults to `DRAFT`.
        trigger:
          $ref: '#/components/schemas/EarningRuleTrigger'
        earnings:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EarningRuleEarning'
          description: >-
            Array of earning definitions, each with optional rules and required
            effects.
        error:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleError'
            - type: 'null'
          description: Custom error message shown when earning rule conditions are not met.
        validity_hours:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleValidityHours'
            - type: 'null'
          description: Time-of-day restrictions for when the rule is active.
        start_date:
          type:
            - string
            - 'null'
          format: date-time
          description: Start date for rule validity (ISO 8601).
        end_date:
          type:
            - string
            - 'null'
          format: date-time
          description: End date for rule validity (ISO 8601).
        trigger_limits:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleTriggerLimits'
            - type: 'null'
          description: >-
            Cooldown and frequency limits for how often the rule can trigger per
            customer.
        metadata:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: Custom key-value metadata.
      additionalProperties: false
    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
    EarningRuleTrigger:
      type: object
      required:
        - event
      properties:
        event:
          type: string
          enum:
            - customer.order.paid
            - customer.custom_event
            - customer.segment.entered
          description: >
            The event that triggers this earning rule.

            - `customer.order.paid`: Triggered when a customer's order is paid.

            - `customer.custom_event`: Triggered by a custom event (requires
            `custom_event`).

            - `customer.segment.entered`: Triggered when a customer enters a
            segment (requires `segment`).
        custom_event:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleTriggerCustomEvent'
            - type: 'null'
          description: >-
            Required when `event` is `customer.custom_event`. Must be `null`
            otherwise.
        segment:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleTriggerSegment'
            - type: 'null'
          description: >-
            Required when `event` is `customer.segment.entered`. Must be `null`
            otherwise.
      additionalProperties: false
    EarningRuleEarning:
      type: object
      required:
        - effects
      properties:
        name:
          type:
            - string
            - 'null'
          description: Optional name for this earning definition.
        rules:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleRulesGroup'
            - type: 'null'
          description: Optional validation rules that must pass before effects are applied.
        effects:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EarningRuleEffect'
          description: Effects to apply when rules pass (at least one required).
        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'
      additionalProperties: false
    EarningRuleError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 200
          description: Custom error message when rule conditions are not satisfied.
      additionalProperties: false
    EarningRuleValidityHours:
      type: object
      required:
        - daily
      properties:
        daily:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EarningRuleValidityDailyHours'
          description: >-
            Array of daily time windows. Overlapping windows for the same day
            are not allowed.
      additionalProperties: false
    EarningRuleTriggerLimits:
      type: object
      properties:
        cooldown:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsCooldown'
            - type: 'null'
          description: Cooldown configuration. Defaults to `NO_COOLDOWN`.
        frequency:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsFrequency'
            - type: 'null'
          description: Frequency limit configuration. Defaults to `NO_LIMIT`.
      additionalProperties: false
    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'
    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
    EarningRuleTriggerCustomEvent:
      type: object
      required:
        - schema_id
      properties:
        schema_id:
          type: string
          description: ID of the custom event schema.
      additionalProperties: false
    EarningRuleTriggerSegment:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the segment.
      additionalProperties: false
    EarningRuleRulesGroup:
      type: object
      required:
        - logic
      properties:
        logic:
          type: string
          description: |
            Logical formula combining rule definitions by their numeric keys.
            Supports `AND`, `OR`, and parentheses. Example: `"1 AND (2 OR 3)"`.
      additionalProperties:
        $ref: '#/components/schemas/EarningRuleDefinition'
      description: >
        A rules group containing a `logic` formula key and numbered rule
        definitions.

        Keys other than `logic` must be positive integers (e.g., `"1"`, `"2"`,
        `"3"`).

        Minimum 2 properties (logic + at least one rule definition).
    EarningRuleEffect:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - POINTS
            - POINTS_PROPORTIONAL
            - INCENTIVE
          description: >
            The type of effect:

            - `POINTS`: Awards a fixed number of points.

            - `POINTS_PROPORTIONAL`: Awards points proportional to
            order/customer values.

            - `INCENTIVE`: Awards a predefined incentive.
        points:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectPoints'
            - type: 'null'
          description: Required when `type` is `POINTS`. Must be `null` otherwise.
        points_proportional:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectPointsProportional'
            - type: 'null'
          description: >-
            Required when `type` is `POINTS_PROPORTIONAL`. Must be `null`
            otherwise.
        incentive:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleEffectIncentive'
            - type: 'null'
          description: Required when `type` is `INCENTIVE`. Must be `null` otherwise.
      additionalProperties: false
    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
    EarningRuleValidityDailyHours:
      type: object
      required:
        - days_of_week
        - start_time
        - end_time
      properties:
        days_of_week:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
          minItems: 1
          maxItems: 7
          uniqueItems: true
          description: Days of week (0=Sunday, 6=Saturday).
        start_time:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: Start time in `HH:mm` format. Must be before `end_time`.
        end_time:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: End time in `HH:mm` format.
      additionalProperties: false
    TriggerLimitsCooldown:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NO_COOLDOWN
            - FIXED_COOLDOWN
          description: >
            - `NO_COOLDOWN`: No cooldown period between triggers.

            - `FIXED_COOLDOWN`: Requires `fixed_cooldown` with period
            configuration.
        fixed_cooldown:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsCooldownFixedCooldown'
            - type: 'null'
          description: >-
            Required when `type` is `FIXED_COOLDOWN`. Must be null for
            `NO_COOLDOWN`.
      additionalProperties: false
    TriggerLimitsFrequency:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
          description: >
            - `NO_LIMIT`: No frequency restrictions.

            - `LIMITED`: Requires `limits` array with exactly one limit
            configuration.
        limits:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/TriggerLimitsFrequencyLimit'
              minItems: 0
              maxItems: 1
            - type: 'null'
          description: |
            When `type` is `LIMITED`, must be an array with exactly 1 item.
            When `type` is `NO_LIMIT`, must be empty array or null.
      additionalProperties: false
    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'
    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'
    EarningRuleDefinition:
      type: object
      properties:
        name:
          type: string
          enum:
            - customer.segment
            - customer.metadata
            - order.amount
            - order.initial_amount
            - order.total_amount
            - order.metadata
            - order.items.count
            - order.items.price_any
            - order.items.price_each
            - order.items.every
            - order.items.any
            - order.items.none
            - order.items.quantity
            - order.items.aggregated_quantity
            - order.items.price
            - order.items.aggregated_amount
            - order.items.cheapest
            - order.items.most_expensive
            - order.items.metadata
            - custom_event.metadata
          description: >
            Rule definition name. Available names depend on the trigger event:

            - `customer.order.paid`: All names except `custom_event.metadata`.

            - `customer.custom_event`: `customer.segment`, `customer.metadata`,
            `custom_event.metadata`.

            - `customer.segment.entered`: `customer.segment`,
            `customer.metadata`.
        property:
          type:
            - string
            - 'null'
          description: >-
            Required for metadata-based rules (`customer.metadata`,
            `custom_event.metadata`, `order.items.metadata`, `order.metadata`).
        schema_id:
          type:
            - string
            - 'null'
          description: Optional reference to a metadata schema.
        error:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleError'
            - type: 'null'
        rules:
          oneOf:
            - $ref: '#/components/schemas/EarningRuleRulesGroup'
            - type: 'null'
          description: >-
            Nested child rules (only allowed for `order.items.every`,
            `order.items.any`, `order.items.cheapest`,
            `order.items.most_expensive`).
        conditions:
          $ref: '#/components/schemas/EarningRuleConditions'
      additionalProperties: false
    EarningRuleEffectPoints:
      type: object
      required:
        - value
        - card_definition_id
      properties:
        value:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Fixed number of points to award.
        card_definition_id:
          type: string
          description: ID of the card definition to award points to.
        points_expiration:
          oneOf:
            - $ref: '#/components/schemas/PointsExpiration'
            - type: 'null'
          description: Optional effect-level expiration override for the awarded points.
      additionalProperties: false
    EarningRuleEffectPointsProportional:
      type: object
      required:
        - calculation_type
        - card_definition_id
      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
          description: >
            Determines how proportional points are calculated:

            - `PRE_DISCOUNT_ORDER_AMOUNT`: Based on `order.amount` (before
            discounts).

            - `POST_DISCOUNT_ORDER_AMOUNT`: Based on `order.total_amount` (after
            discounts).

            - `ORDER_METADATA_VALUE`: Based on `order.metadata` (numeric
            metadata property).

            - `CUSTOMER_METADATA_VALUE`: Based on `customer.metadata` (numeric
            metadata property).

            - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`: Based on `order_items.amount`
            (item amount before discounts).

            - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`: Based on
            `order_items.subtotal_amount` (item amount after discounts).

            - `ORDER_ITEMS_QUANTITY`: Based on `order_items.quantity`.
        card_definition_id:
          type: string
          description: ID of the card definition to award points to.
        points_expiration:
          oneOf:
            - $ref: '#/components/schemas/PointsExpiration'
            - type: 'null'
          description: Optional effect-level expiration override.
        order:
          $ref: '#/components/schemas/EarningRulePointsProportionalOrder'
        customer:
          $ref: '#/components/schemas/EarningRulePointsProportionalCustomer'
        order_items:
          $ref: '#/components/schemas/EarningRulePointsProportionalOrderItems'
      additionalProperties: false
      description: >
        Conditional requirements based on `calculation_type`:

        - `PRE_DISCOUNT_ORDER_AMOUNT`: `order` required with `amount`.
        `customer` and `order_items` must be null.

        - `POST_DISCOUNT_ORDER_AMOUNT`: `order` required with `total_amount`.
        `customer` and `order_items` must be null.

        - `ORDER_METADATA_VALUE`: `order` required with `metadata`. `customer`
        and `order_items` must be null.

        - `CUSTOMER_METADATA_VALUE`: `customer` required with `metadata`.
        `order` and `order_items` must be null.

        - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`: `order_items` required with
        `amount`. `order` and `customer` must be null.

        - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`: `order_items` required with
        `subtotal_amount`. `order` and `customer` must be null.

        - `ORDER_ITEMS_QUANTITY`: `order_items` required with `quantity`.
        `order` and `customer` must be null.
    EarningRuleEffectIncentive:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the incentive to award.
      additionalProperties: false
    TriggerLimitsCooldownFixedCooldown:
      type: object
      required:
        - period
      properties:
        period:
          $ref: '#/components/schemas/TriggerLimitsCooldownFixedCooldownPeriod'
      additionalProperties: false
    TriggerLimitsFrequencyLimit:
      type: object
      required:
        - type
        - period
        - triggers
      properties:
        type:
          type: string
          enum:
            - TIME_BASED
        period:
          $ref: '#/components/schemas/TriggerLimitsFrequencyLimitPeriod'
        triggers:
          $ref: '#/components/schemas/TriggerLimitsFrequencyLimitTriggers'
      additionalProperties: false
    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'
    EarningRuleConditions:
      type: object
      properties:
        $is:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $is_not:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $in:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $not_in:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $less_than:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $less_than_or_equal:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $more_than:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $more_than_or_equal:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
        $dow:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
          minItems: 1
          maxItems: 7
          description: Day-of-week filter (0=Sunday, 6=Saturday).
        $from:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EarningRuleConditionObject'
              - type: string
              - type: integer
              - type: boolean
          minItems: 1
      additionalProperties: false
      description: >
        Condition operators applied to the rule definition. Allowed operators
        depend on the rule name:

        - `customer.segment`: `$is`, `$is_not`

        - `order.items.every/any/none/cheapest/most_expensive`: `$is`, `$from`

        - `order.items.count`, `order.items.aggregated_quantity`,
        `order.items.quantity`: `$more_than`, `$is`, `$less_than`,
        `$less_than_or_equal`, `$more_than_or_equal`, `$in`, `$not_in`

        - `order.amount`, `order.initial_amount`, `order.total_amount`,
        `order.items.price_any`, `order.items.price_each`: `$more_than`,
        `$more_than_or_equal`, `$is`, `$less_than`, `$less_than_or_equal`

        - `order.items.aggregated_amount`, `order.items.price`:
        `$more_than_or_equal`, `$is`, `$less_than_or_equal`
    PointsExpiration:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NO_EXPIRATION
            - ROLLING_EXPIRATION
            - CALENDAR_EXPIRATION
            - SLIDING_EXPIRATION
          description: >
            Points expiration strategy:

            - `NO_EXPIRATION`: Points never expire. Other expiration sub-objects
            must be null.

            - `ROLLING_EXPIRATION`: Points expire after a rolling period.
            Requires `rolling_expiration`.

            - `CALENDAR_EXPIRATION`: Points expire on fixed calendar dates.
            Requires `calendar_expiration`.

            - `SLIDING_EXPIRATION`: Expiration resets on customer activity.
            Requires `sliding_expiration`.
        rolling_expiration:
          oneOf:
            - $ref: '#/components/schemas/RollingExpiration'
            - type: 'null'
        calendar_expiration:
          oneOf:
            - $ref: '#/components/schemas/CalendarExpiration'
            - type: 'null'
        sliding_expiration:
          oneOf:
            - $ref: '#/components/schemas/SlidingExpiration'
            - type: 'null'
      additionalProperties: false
    EarningRulePointsProportionalOrder:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/EarningRulePointsProportionalEvery'
        total_amount:
          $ref: '#/components/schemas/EarningRulePointsProportionalEvery'
        metadata:
          $ref: '#/components/schemas/EarningRulePointsProportionalMetadata'
      additionalProperties: false
      description: >-
        Order-based proportional calculation. Provide the sub-property matching
        the `calculation_type`.
    EarningRulePointsProportionalCustomer:
      type: object
      required:
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/EarningRulePointsProportionalMetadata'
      additionalProperties: false
      description: Customer metadata-based proportional calculation.
    EarningRulePointsProportionalOrderItems:
      type: object
      properties:
        amount:
          $ref: >-
            #/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
        subtotal_amount:
          $ref: >-
            #/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
        quantity:
          $ref: >-
            #/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
      additionalProperties: false
      description: >-
        Order items-based proportional calculation. Provide the sub-property
        matching the `calculation_type`.
    TriggerLimitsCooldownFixedCooldownPeriod:
      type: object
      required:
        - value
        - unit
      properties:
        value:
          type: integer
          minimum: 1
          description: |
            Cooldown duration. Maximum depends on unit:
            - `HOUR`: 1–24
            - `DAY`: 1–90
            - `WEEK`: 1–52
            - `MONTH`: 1–12
            - `YEAR`: 1
        unit:
          type: string
          enum:
            - HOUR
            - DAY
            - WEEK
            - MONTH
            - YEAR
      additionalProperties: false
    TriggerLimitsFrequencyLimitPeriod:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - CURRENT_PERIOD
        current_period:
          oneOf:
            - $ref: '#/components/schemas/TriggerLimitsFrequencyLimitCurrentPeriod'
            - type: 'null'
          description: Required when `type` is `CURRENT_PERIOD`.
      additionalProperties: false
    TriggerLimitsFrequencyLimitTriggers:
      type: object
      required:
        - max
      properties:
        max:
          type: integer
          minimum: 1
          description: Maximum number of triggers allowed within the frequency period.
      additionalProperties: false
    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'
    EarningRuleConditionObject:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        source_id:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
      additionalProperties: false
    RollingExpiration:
      type: object
      required:
        - period
      properties:
        period:
          $ref: '#/components/schemas/RollingExpirationPeriod'
        rounding:
          oneOf:
            - $ref: '#/components/schemas/RollingExpirationRounding'
            - type: 'null'
          description: Optional rounding to snap expiration to period boundaries.
      additionalProperties: false
    CalendarExpiration:
      type: object
      required:
        - expiration_dates
      properties:
        expiration_dates:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/CalendarExpirationDate'
          description: Fixed dates when points expire (max 20).
      additionalProperties: false
    SlidingExpiration:
      type: object
      required:
        - period
      properties:
        earning_activity:
          type: boolean
          description: Reset expiration on earning activity.
        spending_activity:
          type: boolean
          description: Reset expiration on spending activity.
        custom_activity:
          type: boolean
          description: Reset expiration on custom activity types.
        custom_activity_types:
          oneOf:
            - type: array
              items:
                type: string
              minItems: 1
              maxItems: 10
              uniqueItems: true
              description: Required when `custom_activity` is `true`. Max 10 unique items.
            - type: 'null'
        period:
          $ref: '#/components/schemas/SlidingExpirationPeriod'
      additionalProperties: false
      description: >
        At least one of `earning_activity`, `spending_activity`, or
        `custom_activity` must be `true`.

        When `custom_activity` is `true`, `custom_activity_types` is required
        with 1–10 unique string items.
    EarningRulePointsProportionalEvery:
      type: object
      required:
        - every
        - value
      properties:
        every:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: The divisor (e.g., every 1000 cents spent).
        value:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Points awarded per `every` unit.
      additionalProperties: false
    EarningRulePointsProportionalMetadata:
      type: object
      required:
        - every
        - value
        - property
      properties:
        every:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        value:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        property:
          type: string
          minLength: 1
          description: The metadata property name to read the numeric value from.
      additionalProperties: false
    EarningRulePointsProportionalOrderItemsCalculation:
      type: object
      required:
        - every
        - value
        - applicable_to
      properties:
        every:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        value:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        applicable_to:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EarningRulePointsProportionalApplicableTo'
          description: >-
            Product, SKU, or collection criteria for filtering matching order
            items.
      additionalProperties: false
    TriggerLimitsFrequencyLimitCurrentPeriod:
      type: object
      required:
        - unit
      properties:
        unit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - QUARTER
            - YEAR
          description: The time period unit for frequency limiting.
      additionalProperties: false
    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'
    RollingExpirationPeriod:
      type: object
      required:
        - unit
        - value
      properties:
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        value:
          type: integer
          minimum: 1
          description: |
            Maximum value depends on unit:
            - `DAY`: 1–90
            - `MONTH`: 1–12
            - `YEAR`: 1–5
      additionalProperties: false
    RollingExpirationRounding:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - END_OF_MONTH
            - END_OF_QUARTER
            - END_OF_HALF_YEAR
            - END_OF_YEAR
            - END_OF_PARTICULAR_MONTH
          description: >
            Rounding strategy. When `END_OF_PARTICULAR_MONTH`, `value` is
            required (1–12 for month number).

            For all other types, `value` must be null.
        value:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 12
            - type: 'null'
          description: Month number (1–12). Required only for `END_OF_PARTICULAR_MONTH`.
      additionalProperties: false
    CalendarExpirationDate:
      type: object
      required:
        - day
        - month
      properties:
        day:
          type: integer
          minimum: 1
          maximum: 31
          description: |
            Day of month. Maximum depends on month:
            - Months 1,3,5,7,8,10,12: max 31
            - Months 4,6,9,11: max 30
            - Month 2: max 29
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: Month number (1–12).
      additionalProperties: false
    SlidingExpirationPeriod:
      type: object
      required:
        - value
        - unit
      properties:
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        value:
          type: integer
          minimum: 1
          description: |
            Maximum value depends on unit:
            - `DAY`: 1–90
            - `MONTH`: 1–12
            - `YEAR`: 1
      additionalProperties: false
    EarningRulePointsProportionalApplicableTo:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - product
            - sku
            - products_collection
          description: >
            Type of applicable-to target:

            - `product`: Requires `product` sub-object with `id`.

            - `sku`: Requires `sku` sub-object with `id`.

            - `products_collection`: Requires `products_collection` sub-object
            with `id`.
        product:
          $ref: >-
            #/components/schemas/EarningRulePointsProportionalApplicableToProduct
        sku:
          $ref: '#/components/schemas/EarningRulePointsProportionalApplicableToSku'
        products_collection:
          $ref: >-
            #/components/schemas/EarningRulePointsProportionalApplicableToProductsCollection
      additionalProperties: false
      description: >
        Only the sub-object matching `type` should be provided; others must be
        null.
    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'
    EarningRulePointsProportionalApplicableToProduct:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Product ID.
      additionalProperties: false
    EarningRulePointsProportionalApplicableToSku:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: SKU ID.
      additionalProperties: false
    EarningRulePointsProportionalApplicableToProductsCollection:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Products collection ID.
      additionalProperties: false
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      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

````