--- title: "List Card Definitions" method: GET path: "/v2/loyalties/card-definitions" tags: ["Card Definitions"] --- # List Card Definitions `GET /v2/loyalties/card-definitions` 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` integer - `order` union - '-name' | 'name' | '-type' | 'type' | '-status' | 'status' | '-created_at' | 'created_at' - string[] - `cursor` string - `filters` CardDefinitionListFilters — Filters for the card definitions list endpoint. Each field accepts a `conditions` object; provided conditions must be valid for the field type. - `junction` 'AND' | 'OR' | 'null', nullable — Logical junction between field filters. Defaults to `AND`. - `id` CardDefinitionIdFilter — 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 — ID equals the given value. - string - string[] - `$is_not` union — ID does not equal the given value. - string - string[] - `$in` union — ID is one of the given values (up to 100). - string - string[] - `$not_in` union — ID is none of the given values (up to 100). - string - string[] - `name` CardDefinitionStringFilter — 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 — Value equals the given string. - string - string[] - `$is_not` union — Value does not equal the given string. - string - string[] - `$contains` union — Value contains the given substring. - string - string[] - `$not_contain` union — Value does not contain the given substring. - string - string[] - `$starts_with` union — Value starts with the given prefix. - string - string[] - `$ends_with` union — Value ends with the given suffix. - string - string[] - `$in` union — Value is one of the given strings (up to 10). - string - string[] - `$not_in` union — Value is none of the given strings (up to 10). - string - string[] - `$has_value` string — Field has a value (presence check; the provided value is ignored). - `$is_unknown` string — Field has no value (presence check; the provided value is ignored). - `type` CardDefinitionTypeFilter — 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 — Type equals the given value. - 'INDIVIDUAL' - string[] - `$is_not` union — Type does not equal the given value. - 'INDIVIDUAL' - string[] - `$in` union — Type is one of the given values (up to 10). - 'INDIVIDUAL' - string[] - `$not_in` union — Type is none of the given values (up to 10). - 'INDIVIDUAL' - string[] - `status` CardDefinitionStatusFilter — 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 — Status equals the given value. - 'ACTIVE' | 'DRAFT' - string[] - `$is_not` union — Status does not equal the given value. - 'ACTIVE' | 'DRAFT' - string[] - `$in` union — Status is one of the given values (up to 10). - 'ACTIVE' | 'DRAFT' - string[] - `$not_in` union — Status is none of the given values (up to 10). - '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 — Date is before the given date (a date string). - string - string[] - `$after` union — Date is after the given date (a date string). - string - string[] - `$is` union — Date matches the given value expressed as a non-negative integer number of days. - string - string[] - `$more_than` union — Date is more than the given non-negative integer number of days ago. - string - string[] - `$less_than` union — Date is less than the given non-negative integer number of days ago. - string - string[] - `$has_value` string — Field has a value (presence check; the provided value is ignored). - `$is_unknown` string — Field has no value (presence check; the provided 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 — Date is before the given date (a date string). - string - string[] - `$after` union — Date is after the given date (a date string). - string - string[] - `$is` union — Date matches the given value expressed as a non-negative integer number of days. - string - string[] - `$more_than` union — Date is more than the given non-negative integer number of days ago. - string - string[] - `$less_than` union — Date is less than the given non-negative integer number of days ago. - string - string[] - `$has_value` string — Field has a value (presence check; the provided value is ignored). - `$is_unknown` string — Field has no value (presence check; the provided value is ignored). ## Response `200` A paginated list of card definitions. - CardDefinitionListResponse — 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` CardDefinitionCodeConfig, 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` CardDefinitionPeriod, required — A period expressed as a value and unit. - `value` integer, required — Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Period unit. - `rounding` CardDefinitionPointsExpirationRollingExpirationRounding — 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` CardDefinitionCalendarDate[], 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` CardDefinitionPeriod, 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` CardDefinitionPeriod, 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` CardDefinitionCalendarDate[], 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` CardDefinitionPeriod, 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` CardDefinitionEarningLimitsTransactionsLimit[], 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` CardDefinitionSpendingLimitsTransactionsLimit[], 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` CardDefinitionRefundsSpentPointsMethod[], 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` CardDefinitionRefundsEarnedPointsMethod[], 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` CardDefinitionBalanceSettings, 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` CardDefinitionPayWithPoints, 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 --- [API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/revisions/69be73b5cff0/schema)