> ## 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 Card Definition

> ⚠️ **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 card definition with the specified configuration.

Required fields: `name`, `type`. All other fields have sensible defaults.
The `code_config` is optional on input but required internally (defaults are generated).

**Custom validators applied:**
- `createCardDefinitionBalanceSettings`: `balance_settings.allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`.
- `createCardDefinitionRefunds`: `refunds.earned_points.methods` with type `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative: true`. Method type `REVOKE_FROM_PENDING` requires `pending_points.type` to be one of `PERIOD_BASED`, `FIXED_DATES`, or `EVENT_BASED`.




## OpenAPI

````yaml /openapi/loyalties-v2.json post /v2/loyalties/card-definitions
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/card-definitions:
    post:
      tags:
        - Card Definitions
      summary: Create Card Definition
      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 card definition with the specified configuration.


        Required fields: `name`, `type`. All other fields have sensible
        defaults.

        The `code_config` is optional on input but required internally (defaults
        are generated).


        **Custom validators applied:**

        - `createCardDefinitionBalanceSettings`:
        `balance_settings.allow_negative` can only be `true` when
        `points_expiration.type` is `NO_EXPIRATION`.

        - `createCardDefinitionRefunds`: `refunds.earned_points.methods` with
        type `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative:
        true`. Method type `REVOKE_FROM_PENDING` requires `pending_points.type`
        to be one of `PERIOD_BASED`, `FIXED_DATES`, or `EVENT_BASED`.
      operationId: createCardDefinition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardDefinitionCreateRequest'
      responses:
        '200':
          description: Created card definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardDefinitionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CardDefinitionCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        type:
          type: string
          enum:
            - INDIVIDUAL
        status:
          type:
            - string
            - 'null'
          enum:
            - DRAFT
            - ACTIVE
            - null
          default: DRAFT
          description: Initial status. Defaults to `DRAFT` if not provided.
        code_config:
          oneOf:
            - $ref: '#/components/schemas/CodeConfigRequest'
            - type: 'null'
          description: >-
            Code generation configuration. Defaults to 10-character alphanumeric
            pattern if not provided.
        points_expiration:
          oneOf:
            - $ref: '#/components/schemas/PointsExpirationRequest'
            - type: 'null'
          description: Points expiration policy. Defaults to `NO_EXPIRATION`.
        pending_points:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsRequest'
            - type: 'null'
          description: Pending points policy. Defaults to `IMMEDIATE`.
        earning_limits:
          oneOf:
            - $ref: '#/components/schemas/EarningLimitsRequest'
            - type: 'null'
          description: Earning limits configuration. Defaults to no limits.
        spending_limits:
          oneOf:
            - $ref: '#/components/schemas/SpendingLimitsRequest'
            - type: 'null'
          description: Spending limits configuration. Defaults to no limits.
        refunds:
          oneOf:
            - $ref: '#/components/schemas/RefundsRequest'
            - type: 'null'
          description: Refund policies. Defaults to no refunds.
        balance_settings:
          oneOf:
            - $ref: '#/components/schemas/BalanceSettingsRequest'
            - type: 'null'
          description: 'Balance settings. Defaults to `allow_negative: false`.'
        metadata:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
      required:
        - name
        - type
      additionalProperties: false
    CardDefinitionResponse:
      type: object
      description: Full card definition DTO returned by all CRUD endpoints.
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - INDIVIDUAL
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - INACTIVE
            - DELETED
        code_config:
          $ref: '#/components/schemas/CodeConfigDTO'
        points_expiration:
          $ref: '#/components/schemas/PointsExpirationDTO'
        pending_points:
          $ref: '#/components/schemas/PendingPointsDTO'
        earning_limits:
          $ref: '#/components/schemas/EarningLimitsDTO'
        spending_limits:
          $ref: '#/components/schemas/SpendingLimitsDTO'
        refunds:
          $ref: '#/components/schemas/RefundsDTO'
        balance_settings:
          $ref: '#/components/schemas/BalanceSettingsDTO'
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        object:
          type: string
          const: card_definition
      required:
        - id
        - name
        - type
        - status
        - code_config
        - points_expiration
        - pending_points
        - earning_limits
        - spending_limits
        - refunds
        - balance_settings
        - metadata
        - created_at
        - object
    CodeConfigRequest:
      type: object
      description: >-
        Code generation configuration. If not provided on create, defaults to a
        10-character alphanumeric pattern.
      properties:
        length:
          type:
            - integer
            - 'null'
          description: Number of random characters. Mutually derived with `pattern`.
        charset:
          type:
            - string
            - 'null'
          description: Character set for code generation.
        prefix:
          type:
            - string
            - 'null'
        postfix:
          type:
            - string
            - 'null'
        pattern:
          type:
            - string
            - 'null'
          description: Code pattern with `#` placeholders for random characters.
      additionalProperties: false
    PointsExpirationRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_EXPIRATION
            - ROLLING_EXPIRATION
            - CALENDAR_EXPIRATION
            - SLIDING_EXPIRATION
        rolling_expiration:
          oneOf:
            - $ref: '#/components/schemas/RollingExpirationRequest'
            - type: 'null'
          description: Required when type is `ROLLING_EXPIRATION`. Must be null otherwise.
        calendar_expiration:
          oneOf:
            - $ref: '#/components/schemas/CalendarExpirationRequest'
            - type: 'null'
          description: Required when type is `CALENDAR_EXPIRATION`. Must be null otherwise.
        sliding_expiration:
          oneOf:
            - $ref: '#/components/schemas/SlidingExpirationRequest'
            - type: 'null'
          description: Required when type is `SLIDING_EXPIRATION`. Must be null otherwise.
      required:
        - type
      additionalProperties: false
    PendingPointsRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - IMMEDIATE
            - PERIOD_BASED
            - FIXED_DATES
            - EVENT_BASED
        period_based:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsPeriodBasedRequest'
            - type: 'null'
          description: Required when type is `PERIOD_BASED`. Must be null otherwise.
        fixed_dates:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsFixedDatesRequest'
            - type: 'null'
          description: Required when type is `FIXED_DATES`. Must be null otherwise.
        event_based:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsEventBasedRequest'
            - type: 'null'
          description: Required when type is `EVENT_BASED`. Must be null otherwise.
      required:
        - type
      additionalProperties: false
    EarningLimitsRequest:
      type: object
      properties:
        global:
          $ref: '#/components/schemas/EarningLimitsGlobalRequest'
        transactions:
          $ref: '#/components/schemas/EarningLimitsTransactionsRequest'
      required:
        - global
        - transactions
      additionalProperties: false
    SpendingLimitsRequest:
      type: object
      properties:
        global:
          $ref: '#/components/schemas/SpendingLimitsGlobalRequest'
        transactions:
          $ref: '#/components/schemas/SpendingLimitsTransactionsRequest'
      required:
        - global
        - transactions
      additionalProperties: false
    RefundsRequest:
      type: object
      properties:
        spent_points:
          $ref: '#/components/schemas/RefundsSpentPointsRequest'
        earned_points:
          $ref: '#/components/schemas/RefundsEarnedPointsRequest'
      required:
        - spent_points
        - earned_points
      additionalProperties: false
    BalanceSettingsRequest:
      type: object
      properties:
        allow_negative:
          type: boolean
          description: Can only be `true` when `points_expiration.type` is `NO_EXPIRATION`.
      required:
        - allow_negative
      additionalProperties: false
    CodeConfigDTO:
      type: object
      properties:
        pattern:
          type: string
          description: >-
            Code pattern using `#` as placeholder for random characters.
            Default: 10 `#` characters.
        length:
          type: integer
          description: Number of random characters in the pattern.
        charset:
          type: string
          description: >-
            Characters used for code generation. Default: alphanumeric
            (0-9a-zA-Z).
        prefix:
          type: string
          description: Prefix prepended to generated codes.
        postfix:
          type: string
          description: Postfix appended to generated codes.
      required:
        - pattern
        - length
        - charset
        - prefix
        - postfix
    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
    PendingPointsDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - IMMEDIATE
            - PERIOD_BASED
            - FIXED_DATES
            - EVENT_BASED
        period_based:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsPeriodBasedDTO'
            - type: 'null'
        fixed_dates:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsFixedDatesDTO'
            - type: 'null'
        event_based:
          oneOf:
            - $ref: '#/components/schemas/PendingPointsEventBasedDTO'
            - type: 'null'
      required:
        - type
    EarningLimitsDTO:
      type: object
      properties:
        global:
          $ref: '#/components/schemas/EarningLimitsGlobalDTO'
        transactions:
          $ref: '#/components/schemas/EarningLimitsTransactionsDTO'
      required:
        - global
        - transactions
    SpendingLimitsDTO:
      type: object
      properties:
        global:
          $ref: '#/components/schemas/SpendingLimitsGlobalDTO'
        transactions:
          $ref: '#/components/schemas/SpendingLimitsTransactionsDTO'
      required:
        - global
        - transactions
    RefundsDTO:
      type: object
      properties:
        spent_points:
          $ref: '#/components/schemas/RefundsSpentPointsDTO'
        earned_points:
          $ref: '#/components/schemas/RefundsEarnedPointsDTO'
      required:
        - spent_points
        - earned_points
    BalanceSettingsDTO:
      type: object
      properties:
        allow_negative:
          type: boolean
          description: >-
            Whether the card balance can go below zero. Can only be `true` when
            `points_expiration.type` is `NO_EXPIRATION`.
      required:
        - allow_negative
    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
    RollingExpirationRequest:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/RollingExpirationPeriodRequest'
        rounding:
          oneOf:
            - $ref: '#/components/schemas/RollingRoundingRequest'
            - type: 'null'
      required:
        - period
      additionalProperties: false
    CalendarExpirationRequest:
      type: object
      properties:
        expiration_dates:
          type: array
          items:
            $ref: '#/components/schemas/DayMonthRequest'
          minItems: 1
          maxItems: 20
      required:
        - expiration_dates
      additionalProperties: false
    SlidingExpirationRequest:
      type: object
      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 items.
      properties:
        earning_activity:
          type: boolean
        spending_activity:
          type: boolean
        custom_activity:
          type: boolean
        custom_activity_types:
          oneOf:
            - type: array
              items:
                type: string
              minItems: 1
              maxItems: 10
            - type: 'null'
        period:
          $ref: '#/components/schemas/SlidingExpirationPeriodRequest'
      required:
        - period
      additionalProperties: false
    PendingPointsPeriodBasedRequest:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/PendingPointsPeriodRequest'
      required:
        - period
      additionalProperties: false
    PendingPointsFixedDatesRequest:
      type: object
      properties:
        dates:
          type: array
          items:
            $ref: '#/components/schemas/DayMonthRequest'
          minItems: 1
          maxItems: 20
      required:
        - dates
      additionalProperties: false
    PendingPointsEventBasedRequest:
      type: object
      properties:
        event_types:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: Unique custom event type IDs.
        cancel_period:
          $ref: '#/components/schemas/EventBasedCancelPeriodRequest'
      required:
        - event_types
        - cancel_period
      additionalProperties: false
    EarningLimitsGlobalRequest:
      type: object
      description: >-
        When `NO_LIMIT`, limits must be empty or null. When `LIMITED`, exactly 1
        limit is required.
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/EarningLimitsGlobalLimitRequest'
              minItems: 0
              maxItems: 1
      required:
        - type
      additionalProperties: false
    EarningLimitsTransactionsRequest:
      type: object
      description: >-
        When `NO_LIMIT`, limits must be empty or null. When `LIMITED`, at least
        1 limit is required with unique types.
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/EarningLimitsTransactionsLimitRequest'
              minItems: 0
      required:
        - type
      additionalProperties: false
    SpendingLimitsGlobalRequest:
      type: object
      description: >-
        When `NO_LIMIT`, limits must be empty or null. When `LIMITED`, at least
        1 limit is required with unique types.
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/SpendingLimitsGlobalLimitRequest'
              minItems: 0
              maxItems: 1
      required:
        - type
      additionalProperties: false
    SpendingLimitsTransactionsRequest:
      type: object
      description: >-
        When `NO_LIMIT`, limits must be empty or null. When `LIMITED`, exactly 1
        limit is required.
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/SpendingLimitsTransactionsLimitRequest'
              minItems: 0
              maxItems: 1
      required:
        - type
      additionalProperties: false
    RefundsSpentPointsRequest:
      type: object
      description: >-
        When `NONE`, methods must be empty or null. When `REFUNDABLE`, exactly 1
        method of type `RETURN_POINTS` is required.
      properties:
        type:
          type: string
          enum:
            - NONE
            - REFUNDABLE
        methods:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/RefundsSpentPointsMethodRequest'
              minItems: 0
              maxItems: 1
      required:
        - type
      additionalProperties: false
    RefundsEarnedPointsRequest:
      type: object
      description: >
        When `NONE`, methods must be empty or null. When `REFUNDABLE`, exactly 1
        method is required.

        `REVOKE_FROM_PENDING` requires pending points to be enabled (type not
        `IMMEDIATE`).

        `REVOKE_FROM_BALANCE` with mode `REVOKE_BELOW_ZERO` requires
        `balance_settings.allow_negative: true`.
      properties:
        type:
          type: string
          enum:
            - NONE
            - REFUNDABLE
        methods:
          oneOf:
            - type: 'null'
            - type: array
              items:
                $ref: '#/components/schemas/RefundsEarnedPointsMethodRequest'
              minItems: 0
              maxItems: 1
      required:
        - type
      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
    PendingPointsPeriodBasedDTO:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/PeriodValueUnitDTO'
      required:
        - period
    PendingPointsFixedDatesDTO:
      type: object
      properties:
        dates:
          type: array
          items:
            $ref: '#/components/schemas/DayMonthDTO'
      required:
        - dates
    PendingPointsEventBasedDTO:
      type: object
      properties:
        event_types:
          type: array
          items:
            type: string
          description: Custom event type IDs that trigger point activation.
        cancel_period:
          $ref: '#/components/schemas/PeriodValueUnitDTO'
      required:
        - event_types
        - cancel_period
    EarningLimitsGlobalDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          type: array
          items:
            $ref: '#/components/schemas/EarningLimitsGlobalLimitDTO'
      required:
        - type
        - limits
    EarningLimitsTransactionsDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          type: array
          items:
            $ref: '#/components/schemas/EarningLimitsTransactionsLimitDTO'
      required:
        - type
        - limits
    SpendingLimitsGlobalDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          type: array
          items:
            $ref: '#/components/schemas/SpendingLimitsGlobalLimitDTO'
      required:
        - type
        - limits
    SpendingLimitsTransactionsDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NO_LIMIT
            - LIMITED
        limits:
          type: array
          items:
            $ref: '#/components/schemas/SpendingLimitsTransactionsLimitDTO'
      required:
        - type
        - limits
    RefundsSpentPointsDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NONE
            - REFUNDABLE
        methods:
          type: array
          items:
            $ref: '#/components/schemas/RefundsSpentPointsMethodDTO'
      required:
        - type
        - methods
    RefundsEarnedPointsDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - NONE
            - REFUNDABLE
        methods:
          type: array
          items:
            $ref: '#/components/schemas/RefundsEarnedPointsMethodDTO'
      required:
        - type
        - methods
    RollingExpirationPeriodRequest:
      type: object
      description: 'Max values vary by unit: DAY=90, MONTH=12, YEAR=5.'
      properties:
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        value:
          type: integer
          minimum: 1
      required:
        - unit
        - value
      additionalProperties: false
    RollingRoundingRequest:
      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:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 12
            - type: 'null'
          description: >-
            Required (1-12) when type is `END_OF_PARTICULAR_MONTH`. Must be null
            for other types.
      required:
        - type
      additionalProperties: false
    DayMonthRequest:
      type: object
      description: >-
        Day/month pair. Day range depends on month (Feb max 29, Apr/Jun/Sep/Nov
        max 30, others max 31).
      properties:
        day:
          type: integer
          minimum: 1
          maximum: 31
        month:
          type: integer
          minimum: 1
          maximum: 12
      required:
        - day
        - month
      additionalProperties: false
    SlidingExpirationPeriodRequest:
      type: object
      description: 'Max values vary by unit: DAY=90, MONTH=12, YEAR=1.'
      properties:
        value:
          type: integer
          minimum: 1
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
      required:
        - value
        - unit
      additionalProperties: false
    PendingPointsPeriodRequest:
      type: object
      description: 'Max values vary by unit: DAY=90, MONTH=12, YEAR=1.'
      properties:
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        value:
          type: integer
          minimum: 1
      required:
        - unit
        - value
      additionalProperties: false
    EventBasedCancelPeriodRequest:
      type: object
      description: 'Max values vary by unit: DAY=90, MONTH=12, YEAR=1.'
      properties:
        value:
          type: integer
          minimum: 1
        unit:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
      required:
        - value
        - unit
      additionalProperties: false
    EarningLimitsGlobalLimitRequest:
      type: object
      description: >-
        Discriminated union on `type`. `BALANCE_BASED` requires `max`.
        `TIME_BASED` requires `period` and `points`.
      properties:
        type:
          type: string
          enum:
            - BALANCE_BASED
            - TIME_BASED
        max:
          type: integer
          minimum: 1
          description: Required when type is `BALANCE_BASED`.
        period:
          $ref: '#/components/schemas/EarningLimitsGlobalTimeBasedPeriodRequest'
        points:
          $ref: '#/components/schemas/EarningLimitsGlobalTimeBasedPointsRequest'
      required:
        - type
    EarningLimitsTransactionsLimitRequest:
      type: object
      description: >-
        Discriminated union on `type`. `POINTS` requires `max`. `SPENDING`
        requires `min_amount`.
      properties:
        type:
          type: string
          enum:
            - POINTS
            - SPENDING
        max:
          type: integer
          minimum: 1
          description: Required when type is `POINTS`.
        min_amount:
          type: integer
          minimum: 1
          description: Required when type is `SPENDING`.
      required:
        - type
    SpendingLimitsGlobalLimitRequest:
      type: object
      description: >-
        Discriminated union on `type`. `SPENDING_BASED` requires `max`.
        `TIME_BASED` requires `period` and `points`.
      properties:
        type:
          type: string
          enum:
            - SPENDING_BASED
            - TIME_BASED
        max:
          type: integer
          minimum: 1
          description: Required when type is `SPENDING_BASED`.
        period:
          $ref: '#/components/schemas/SpendingLimitsGlobalTimeBasedPeriodRequest'
        points:
          $ref: '#/components/schemas/SpendingLimitsGlobalTimeBasedPointsRequest'
      required:
        - type
    SpendingLimitsTransactionsLimitRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - POINTS
        max:
          type: integer
          minimum: 1
      required:
        - type
        - max
      additionalProperties: false
    RefundsSpentPointsMethodRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - RETURN_POINTS
        mode:
          type: string
          enum:
            - REFUND_ALL
            - REFUND_ITEM
            - REFUND_AMOUNT
      required:
        - type
        - mode
      additionalProperties: false
    RefundsEarnedPointsMethodRequest:
      type: object
      description: >-
        Discriminated union on `type`. `REVOKE_FROM_PENDING` needs no extra
        fields. `REVOKE_FROM_BALANCE` requires `mode`.
      properties:
        type:
          type: string
          enum:
            - REVOKE_FROM_PENDING
            - REVOKE_FROM_BALANCE
        mode:
          type: string
          enum:
            - REVOKE_TO_ZERO
            - REVOKE_BELOW_ZERO
          description: Required when type is `REVOKE_FROM_BALANCE`.
      required:
        - type
    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
    EarningLimitsGlobalLimitDTO:
      type: object
      description: >-
        Discriminated by `type`. Either `BALANCE_BASED` (with `max`) or
        `TIME_BASED` (with `period` and `points`).
      properties:
        type:
          type: string
          enum:
            - BALANCE_BASED
            - TIME_BASED
        max:
          type: integer
          minimum: 1
          description: Maximum balance. Present when type is `BALANCE_BASED`.
        period:
          $ref: '#/components/schemas/EarningLimitsTimeBasedPeriodDTO'
        points:
          $ref: '#/components/schemas/PointsMaxDTO'
      required:
        - type
    EarningLimitsTransactionsLimitDTO:
      type: object
      description: >-
        Discriminated by `type`. Either `POINTS` (with `max`) or `SPENDING`
        (with `min_amount`).
      properties:
        type:
          type: string
          enum:
            - POINTS
            - SPENDING
        max:
          type: integer
          minimum: 1
          description: Maximum points per transaction. Present when type is `POINTS`.
        min_amount:
          type: integer
          minimum: 1
          description: >-
            Minimum spending amount required to earn points. Present when type
            is `SPENDING`.
      required:
        - type
    SpendingLimitsGlobalLimitDTO:
      type: object
      description: >-
        Discriminated by `type`. Either `SPENDING_BASED` (with `max`) or
        `TIME_BASED` (with `period` and `points`).
      properties:
        type:
          type: string
          enum:
            - SPENDING_BASED
            - TIME_BASED
        max:
          type: integer
          minimum: 1
          description: Maximum spending points. Present when type is `SPENDING_BASED`.
        period:
          $ref: '#/components/schemas/SpendingLimitsTimeBasedPeriodDTO'
        points:
          $ref: '#/components/schemas/PointsMaxDTO'
      required:
        - type
    SpendingLimitsTransactionsLimitDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - POINTS
        max:
          type: integer
          minimum: 1
          description: Maximum points per spending transaction.
      required:
        - type
        - max
    RefundsSpentPointsMethodDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - RETURN_POINTS
        mode:
          type: string
          enum:
            - REFUND_ALL
            - REFUND_ITEM
            - REFUND_AMOUNT
      required:
        - type
        - mode
    RefundsEarnedPointsMethodDTO:
      type: object
      description: >-
        Discriminated by `type`. `REVOKE_FROM_PENDING` has no extra fields.
        `REVOKE_FROM_BALANCE` includes `mode`.
      properties:
        type:
          type: string
          enum:
            - REVOKE_FROM_PENDING
            - REVOKE_FROM_BALANCE
        mode:
          type: string
          enum:
            - REVOKE_TO_ZERO
            - REVOKE_BELOW_ZERO
          description: Present only when type is `REVOKE_FROM_BALANCE`.
      required:
        - type
    EarningLimitsGlobalTimeBasedPeriodRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - CURRENT_PERIOD
        current_period:
          oneOf:
            - $ref: '#/components/schemas/EarningLimitsCurrentPeriodRequest'
            - type: 'null'
          description: Required when type is `CURRENT_PERIOD`.
      required:
        - type
      additionalProperties: false
    EarningLimitsGlobalTimeBasedPointsRequest:
      type: object
      properties:
        max:
          type: integer
          minimum: 1
          maximum: 2147483647
      required:
        - max
      additionalProperties: false
    SpendingLimitsGlobalTimeBasedPeriodRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - CURRENT_PERIOD
        current_period:
          oneOf:
            - $ref: '#/components/schemas/SpendingLimitsCurrentPeriodRequest'
            - type: 'null'
          description: Required when type is `CURRENT_PERIOD`.
      required:
        - type
      additionalProperties: false
    SpendingLimitsGlobalTimeBasedPointsRequest:
      type: object
      properties:
        max:
          type: integer
          minimum: 1
          maximum: 2147483647
      required:
        - max
      additionalProperties: false
    EarningLimitsTimeBasedPeriodDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - CURRENT_PERIOD
        current_period:
          oneOf:
            - $ref: '#/components/schemas/CurrentPeriodDTO'
            - type: 'null'
      required:
        - type
    PointsMaxDTO:
      type: object
      properties:
        max:
          type: integer
          minimum: 1
          maximum: 2147483647
      required:
        - max
    SpendingLimitsTimeBasedPeriodDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - CURRENT_PERIOD
        current_period:
          oneOf:
            - $ref: '#/components/schemas/SpendingCurrentPeriodDTO'
            - type: 'null'
      required:
        - type
    EarningLimitsCurrentPeriodRequest:
      type: object
      properties:
        unit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - QUARTER
            - YEAR
      required:
        - unit
      additionalProperties: false
    SpendingLimitsCurrentPeriodRequest:
      type: object
      properties:
        unit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - QUARTER
            - YEAR
      required:
        - unit
      additionalProperties: false
    CurrentPeriodDTO:
      type: object
      properties:
        unit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - QUARTER
            - YEAR
      required:
        - unit
    SpendingCurrentPeriodDTO:
      type: object
      properties:
        unit:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - QUARTER
            - YEAR
      required:
        - unit
  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

````