--- title: "List Card Definitions" method: GET path: "/v2/loyalties/card-definitions" tags: ["Card Definitions"] --- # List Card Definitions `GET /v2/loyalties/card-definitions` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/card-definitions` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - HTTP bearer Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of card definitions. Filtering is supported through the `filters` deep-object query parameter, e.g. `filters[name][conditions][$is]=Standard%20Card`. The same field cannot be requested in both ascending and descending order at the same time. ## Query parameters - `limit` union - number - string - `order` union - '-name' | 'name' | '-type' | 'type' | '-status' | 'status' | '-created_at' | 'created_at' - string[] - `cursor` string, nullable - `filters` LoyaltiesCardDefinitionsListRequestQuery: Request query schema for **GET** `/v2/loyalties/card-definitions`. - `junction` 'AND' | 'OR' | 'null', nullable: Joins the field filters. Allowed values are `AND` and `OR`. Defaults to `AND`. - `id` LoyaltiesCardDefinitionsListRequestQueryId: ID field filter. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Values must match the card definition ID pattern `^lcdef_[a-f0-9]+$`. `$is`/`$is_not` accept a single value (string or 1-element array); `$in`/`$not_in` accept 1-100 values. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. Format `lcdef_[a-f0-9]+`. - string - string[] - `$is_not` union: Excludes one value. A string or a one-element array. Format `lcdef_[a-f0-9]+`. - string - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 100 values. Format `lcdef_[a-f0-9]+`. - string - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 100 values. Format `lcdef_[a-f0-9]+`. - string - string[] - `name` LoyaltiesCardDefinitionsListRequestQueryName: String field filter. Allowed conditions: `$is`, `$is_not`, `$contains`, `$not_contain`, `$starts_with`, `$ends_with`, `$in`, `$not_in`, `$has_value`, `$is_unknown`. Single-value conditions accept a string or a 1-element array; `$in`/`$not_in` accept 1-10 values; `$has_value`/`$is_unknown` are presence checks and ignore the value. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - string - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - string - string[] - `$contains` union: Matches when the value contains the substring. A string or a one-element array. - string - string[] - `$not_contain` union: Excludes values that contain the substring. A string or a one-element array. - string - string[] - `$starts_with` union: Matches when the value starts with the prefix. A string or a one-element array. - string - string[] - `$ends_with` union: Matches when the value ends with the suffix. A string or a one-element array. - string - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - string - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - string - string[] - `$has_value` string: Matches when the field is set. The condition value is ignored. - `$is_unknown` string: Matches when the field is not set. The condition value is ignored. - `type` LoyaltiesCardDefinitionsListRequestQueryType: Enum field filter for the card definition `type` field. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Values must be one of: `INDIVIDUAL`. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - 'INDIVIDUAL' - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - 'INDIVIDUAL' - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - 'INDIVIDUAL' - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - 'INDIVIDUAL' - string[] - `status` LoyaltiesCardDefinitionsListRequestQueryStatus: Enum field filter for the card definition `status` field. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Values must be one of: `ACTIVE`, `DRAFT` (deleted card definitions are not listable). - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - 'ACTIVE' | 'DRAFT' - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - 'ACTIVE' | 'DRAFT' - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `created_at` CardDefinitionDateFilter: Date field filter. Allowed conditions: `$before`, `$after`, `$is`, `$more_than`, `$less_than`, `$has_value`, `$is_unknown`. `$before`/`$after` accept a date string; `$is`/`$more_than`/`$less_than` accept a non-negative integer (number of days); `$has_value`/`$is_unknown` are presence checks. Single values may be passed as a string or a 1-element array. - `conditions` object, required - `$before` union: Matches dates before the given value. An ISO 8601 date-time, as a string or a one-element array. - string - string[] - `$after` union: Matches dates after the given value. An ISO 8601 date-time, as a string or a one-element array. - string - string[] - `$is` union: Matches a date exactly the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$more_than` union: Matches dates more than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$less_than` union: Matches dates less than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$has_value` string: Matches when the field is set. The condition value is ignored. - `$is_unknown` string: Matches when the field is not set. The condition value is ignored. - `updated_at` CardDefinitionDateFilter: Date field filter. Allowed conditions: `$before`, `$after`, `$is`, `$more_than`, `$less_than`, `$has_value`, `$is_unknown`. `$before`/`$after` accept a date string; `$is`/`$more_than`/`$less_than` accept a non-negative integer (number of days); `$has_value`/`$is_unknown` are presence checks. Single values may be passed as a string or a 1-element array. - `conditions` object, required - `$before` union: Matches dates before the given value. An ISO 8601 date-time, as a string or a one-element array. - string - string[] - `$after` union: Matches dates after the given value. An ISO 8601 date-time, as a string or a one-element array. - string - string[] - `$is` union: Matches a date exactly the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$more_than` union: Matches dates more than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$less_than` union: Matches dates less than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$has_value` string: Matches when the field is set. The condition value is ignored. - `$is_unknown` string: Matches when the field is not set. The condition value is ignored. ## Response `200` A paginated list of card definitions. - V2LoyaltiesCardDefinitionsListResponseBody: Cursor-paginated list of card definitions. - `data` CardDefinition[], required: The card definitions in the current page. - `id` string, required: Unique card definition ID. - `name` string, required: Card definition name. - `type` 'INDIVIDUAL', required: Card definition type. - `status` 'DRAFT' | 'ACTIVE' | 'DELETED', required: Current card definition status. - `code_config` LoyaltyV2ActivityCardDefinitionCodeConfig, required: Card code generation configuration. Always present with server-side defaults applied. - `pattern` string, required: Code pattern where each `#` is replaced with a random character from the charset. - `length` integer, required: Number of `#` placeholders in the pattern. - `charset` string, required: Characters used for code generation. - `prefix` string, required: Fixed prefix prepended to every generated code. Empty string when not set. - `postfix` string, required: Fixed postfix appended to every generated code. Empty string when not set. - `points_expiration` CardDefinitionPointsExpiration, required: Points expiration policy. Always present; defaults to `NO_EXPIRATION`. - `type` 'NO_EXPIRATION' | 'ROLLING_EXPIRATION' | 'CALENDAR_EXPIRATION' | 'SLIDING_EXPIRATION', required: Points expiration type. - `rolling_expiration` CardDefinitionPointsExpirationRollingExpiration: Rolling expiration configuration. - `period` LoyaltyV2ActivityCardDefinitionPeriod, required: A period expressed as a value and unit. - `value` integer, required: Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required: Period unit. - `rounding` LoyaltyV2ActivityCardDefinitionPointsExpirationRollingExpirationRounding: Rounding of the rolling expiration date. - `type` 'END_OF_MONTH' | 'END_OF_QUARTER' | 'END_OF_HALF_YEAR' | 'END_OF_YEAR' | 'END_OF_PARTICULAR_MONTH', required: Rounding type. - `value` integer: Month number (1-12). Only present when `type` is `END_OF_PARTICULAR_MONTH`. - `calendar_expiration` CardDefinitionPointsExpirationCalendarExpiration: Calendar expiration configuration. - `expiration_dates` LoyaltyV2ActivityCardDefinitionCalendarDate[], required: Calendar dates on which points expire. - `day` integer, required: Day of the month. - `month` integer, required: Month number (1-12). - `sliding_expiration` CardDefinitionPointsExpirationSlidingExpiration: Sliding expiration configuration. - `earning_activity` boolean: Whether earning points resets the expiration window. - `spending_activity` boolean: Whether spending points resets the expiration window. - `custom_activity` boolean: Whether the configured custom events reset the expiration window. - `custom_activity_types` string[], required: Custom event schema IDs that reset the expiration window. Empty array when `custom_activity` is false. - `period` LoyaltyV2ActivityCardDefinitionPeriod, required: A period expressed as a value and unit. - `value` integer, required: Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required: Period unit. - `pending_points` CardDefinitionPendingPoints, required: Pending points activation policy. Always present; defaults to `IMMEDIATE`. - `type` 'IMMEDIATE' | 'PERIOD_BASED' | 'FIXED_DATES' | 'EVENT_BASED', required: Pending points activation type. - `period_based` CardDefinitionPendingPointsPeriodBased: Period-based pending points activation. - `period` LoyaltyV2ActivityCardDefinitionPeriod, required: A period expressed as a value and unit. - `value` integer, required: Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required: Period unit. - `fixed_dates` CardDefinitionPendingPointsFixedDates: Fixed-dates pending points activation. - `dates` LoyaltyV2ActivityCardDefinitionCalendarDate[], required: Calendar dates on which pending points activate. - `day` integer, required: Day of the month. - `month` integer, required: Month number (1-12). - `event_based` CardDefinitionPendingPointsEventBased: Event-based pending points activation. - `event_types` string[], required: Custom event schema IDs that activate pending points. - `cancel_period` LoyaltyV2ActivityCardDefinitionPeriod, required: A period expressed as a value and unit. - `value` integer, required: Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required: Period unit. - `earning_limits` CardDefinitionEarningLimits, required: Points earning limits. Always present; defaults to `NO_LIMIT` for both scopes. - `global` CardDefinitionEarningLimitsGlobal: Global (per card) earning limits. - `type` 'NO_LIMIT' | 'LIMITED', required: Whether global earning limits apply. - `limits` CardDefinitionEarningLimitsGlobalLimit[], required: Limit definitions. Empty array when `type` is `NO_LIMIT`. - union: A global earning limit: `BALANCE_BASED` or `TIME_BASED`. - object: Balance-based limit. - … - object: Time-based limit. - … - `transactions` CardDefinitionEarningLimitsTransactions: Per-transaction earning limits. - `type` 'NO_LIMIT' | 'LIMITED', required: Whether per-transaction earning limits apply. - `limits` LoyaltyV2ActivityCardDefinitionEarningLimitsTransactionsLimit[], required: Limit definitions. Empty array when `type` is `NO_LIMIT`. - union: A per-transaction earning limit: `POINTS` or `SPENDING`. - object: Points limit. - … - object: Spending threshold. - … - `spending_limits` CardDefinitionSpendingLimits, required: Points spending limits. Always present; defaults to `NO_LIMIT` for both scopes. - `global` CardDefinitionSpendingLimitsGlobal: Global (per card) spending limits. - `type` 'NO_LIMIT' | 'LIMITED', required: Whether global spending limits apply. - `limits` CardDefinitionSpendingLimitsGlobalLimit[], required: Limit definitions. Empty array when `type` is `NO_LIMIT`. - union: A global spending limit: `SPENDING_BASED` or `TIME_BASED`. - object: Spending-based limit. - … - object: Time-based limit. - … - `transactions` CardDefinitionSpendingLimitsTransactions: Per-transaction spending limits. - `type` 'NO_LIMIT' | 'LIMITED', required: Whether per-transaction spending limits apply. - `limits` LoyaltyV2ActivityCardDefinitionSpendingLimitsTransactionsLimit[], required: Limit definitions. Empty array when `type` is `NO_LIMIT`. - `type` 'POINTS', required: Limit type. - `max` integer, required: Maximum points spent per transaction. - `refunds` CardDefinitionRefunds, required: Refund handling configuration. Always present; defaults to `NONE` for both scopes. - `spent_points` CardDefinitionRefundsSpentPoints, required: How points spent on a refunded order are handled. - `type` 'NONE' | 'REFUNDABLE', required: Whether spent points are refundable. - `methods` LoyaltyV2ActivityCardDefinitionRefundsSpentPointsMethod[], required: Refund methods. Empty array when `type` is `NONE`. - `type` 'RETURN_POINTS', required: Refund method type. - `mode` 'REFUND_ALL' | 'REFUND_ITEM' | 'REFUND_AMOUNT', required: Refund mode. - `earned_points` CardDefinitionRefundsEarnedPoints, required: How points earned on a refunded order are handled. - `type` 'NONE' | 'REFUNDABLE', required: Whether earned points are revocable on refund. - `methods` LoyaltyV2ActivityCardDefinitionRefundsEarnedPointsMethod[], required: Revoke methods. Empty array when `type` is `NONE`. - union: An earned points revoke method: `REVOKE_FROM_PENDING` or `REVOKE_FROM_BALANCE`. - object: Revoke earned points from pending points. - … - object: Revoke earned points from the card balance. - … - `balance_settings` LoyaltyV2ActivityCardDefinitionBalanceSettings, required: Card balance settings. Always present; defaults to `allow_negative: false`. - `allow_negative` boolean, required: Whether the card balance is allowed to go below zero. - `pay_with_points` LoyaltyV2ActivityCardDefinitionPayWithPoints, required: Pay-with-points configuration. Always present; defaults to `NO_PAYMENTS`. - `type` 'NO_PAYMENTS' | 'EXCHANGE_RATIO', required: Pay-with-points type. - `exchange_ratio` object: Exchange ratio. Only present when `type` is `EXCHANGE_RATIO`. - `formula` string, required: Exchange ratio formula (always returned as a string). - `metadata` object, required: Arbitrary key-value metadata. Empty object when not set. - `created_at` string, date-time, required: Creation timestamp (ISO 8601). - `updated_at` string, date-time, nullable, required: Last update timestamp (ISO 8601). `null` when the card definition has never been updated. - `object` 'card_definition', required: Object type marker. Always `card_definition`. - `cursor` CardDefinitionListCursor, required: Pagination cursor. - `next` string, required: Cursor ID to pass as the `cursor` query parameter to fetch the next page. - `expires_at` string, date-time: Timestamp after which the cursor expires. - `object` 'list', required: Object type marker. Always `list`. ## Other responses - `400`: Validation error - the request body or query parameters are invalid. - `404`: Resource not found - `409`: Conflict - invalid state transition - `500`: Internal server error. ## Changes - **2026-10-14** (v2) `d29b33490051`: 3 breaking, 3 warning, 1 info - the `allOf[#/components/schemas/CardDefinitionListResponse]/data/items/points_expiration/sliding_expiration` response's property type changed from `object` to no type for status `200` - removed the required property `allOf[#/components/schemas/CardDefinitionListResponse]/data/items/points_expiration/sliding_expiration/custom_activity_types` from the response with the `200` status - removed the required property `allOf[#/components/schemas/CardDefinitionListResponse]/data/items/points_expiration/sliding_expiration/period` from the response with the `200` status - removed the optional property `allOf[#/components/schemas/CardDefinitionListResponse]/data/items/points_expiration/sliding_expiration/custom_activity` from the response with the `200` status - …3 more - …earlier changes not shown [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/card-definitions/get.md) --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)