--- title: "List Card Definitions" method: GET path: "/v2/loyalties/card-definitions" tags: ["Card Definitions"] --- # List Card Definitions `GET /v2/loyalties/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](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/f6f2f3388362/schema)