> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # List Card Definitions > ⚠️ **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. Returns a paginated, cursor-based list of card definitions with optional filtering and ordering. ## OpenAPI ````yaml /openapi/loyalties-v2.json get /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: get: tags: - Card Definitions summary: List Card Definitions 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. Returns a paginated, cursor-based list of card definitions with optional filtering and ordering. operationId: listCardDefinitions parameters: - name: filters[junction] in: query required: false schema: type: string enum: - AND - OR description: Logical junction for combining filter conditions. - name: filters[id][conditions][$is] in: query required: false schema: type: string description: Filter by exact card definition ID. - name: filters[id][conditions][$is_not] in: query required: false schema: type: string description: Exclude card definitions with this ID. - name: filters[id][conditions][$in] in: query required: false schema: type: array items: type: string maxItems: 100 description: Filter by multiple card definition IDs. - name: filters[id][conditions][$not_in] in: query required: false schema: type: array items: type: string maxItems: 100 description: Exclude card definitions with these IDs. - name: filters[name][conditions][$is] in: query required: false schema: type: string description: Filter by exact name. - name: filters[name][conditions][$is_not] in: query required: false schema: type: string description: Exclude by exact name. - name: filters[name][conditions][$contains] in: query required: false schema: type: string description: Filter by name containing substring. - name: filters[name][conditions][$starts_with] in: query required: false schema: type: string description: Filter by name starting with. - name: filters[name][conditions][$ends_with] in: query required: false schema: type: string description: Filter by name ending with. - name: filters[type][conditions][$is] in: query required: false schema: type: string enum: - INDIVIDUAL description: Filter by exact card type. - name: filters[type][conditions][$in] in: query required: false schema: type: array items: type: string enum: - INDIVIDUAL description: Filter by multiple card types. - name: filters[status][conditions][$is] in: query required: false schema: type: string enum: - ACTIVE - INACTIVE - DRAFT description: Filter by exact status. - name: filters[status][conditions][$in] in: query required: false schema: type: array items: type: string enum: - ACTIVE - INACTIVE - DRAFT description: Filter by multiple statuses. - name: filters[created_at][conditions][$before] in: query required: false schema: type: string format: date-time description: Filter for records created before this date. - name: filters[created_at][conditions][$after] in: query required: false schema: type: string format: date-time description: Filter for records created after this date. - name: filters[updated_at][conditions][$before] in: query required: false schema: type: string format: date-time description: Filter for records updated before this date. - name: filters[updated_at][conditions][$after] in: query required: false schema: type: string format: date-time description: Filter for records updated after this date. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of results to return (1-100). - name: order in: query required: false schema: type: array items: type: string enum: - '-name' - name - '-type' - type - '-status' - status - '-created_at' - created_at description: 'Sort order. Prefix with `-` for descending. Default: `-created_at`.' - name: cursor in: query required: false schema: type: string description: Cursor for pagination. Obtained from a previous list response. responses: '200': description: List of card definitions content: application/json: schema: $ref: '#/components/schemas/CardDefinitionListResponse' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CardDefinitionListResponse: type: object properties: object: type: string const: list data: type: array items: $ref: '#/components/schemas/CardDefinitionResponse' cursor: oneOf: - $ref: '#/components/schemas/PaginationCursor' - type: 'null' required: - object - data - cursor 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 PaginationCursor: type: object description: Cursor for fetching the next page of results. properties: next: type: string description: >- Cursor token to pass as the `cursor` query parameter for the next page. expires_at: type: string format: date-time description: ISO 8601 timestamp when this cursor expires. required: - next - expires_at ErrorResponse: type: object description: Standard error response. properties: code: type: integer description: HTTP status code. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional error details. request_id: type: - string - 'null' description: Request identifier for tracing. resource_id: type: string description: Related resource identifier (when applicable). resource_type: type: string description: Related resource type (when applicable). required: - code - key - message 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 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 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 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 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 ````