> ## 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. # Update 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. Updates a card definition. All properties are optional; only provided sections are updated. `type` and `status` cannot be changed through this endpoint (status transitions are performed via the activate/draft endpoints). When the card definition is in use (e.g. assigned to a program with existing cards), updates to restricted sections may be rejected with a resource-locked error; only `name`, `metadata` and `pay_with_points` are always updatable. ## OpenAPI ````yaml /openapi/loyalties-v2.json put /v2/loyalties/card-definitions/{cardDefinitionId} openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - 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: 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: 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: Benefits description: >- Manage benefit 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: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/card-definitions/{cardDefinitionId}: put: tags: - Card Definitions summary: Update 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. Updates a card definition. All properties are optional; only provided sections are updated. `type` and `status` cannot be changed through this endpoint (status transitions are performed via the activate/draft endpoints). When the card definition is in use (e.g. assigned to a program with existing cards), updates to restricted sections may be rejected with a resource-locked error; only `name`, `metadata` and `pay_with_points` are always updatable. operationId: updateCardDefinition parameters: - name: id in: path required: true description: 'Unique card definition ID. Pattern: `^lcdef_[a-f0-9]+$`.' schema: type: string pattern: ^lcdef_[a-f0-9]+$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardDefinitionUpdateRequest' responses: '200': description: The updated card definition. content: application/json: schema: $ref: '#/components/schemas/CardDefinition' '400': description: Validation error - the request body or query parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - invalid state transition content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CardDefinitionUpdateRequest: type: object description: | Request body for updating a card definition. All properties are optional. `type` and `status` cannot be updated. properties: name: type: - string - 'null' minLength: 1 maxLength: 200 description: Card definition name. code_config: oneOf: - $ref: '#/components/schemas/CardDefinitionCodeConfigInput' - type: 'null' description: Card code generation configuration. points_expiration: oneOf: - $ref: '#/components/schemas/CardDefinitionPointsExpirationInput' - type: 'null' description: Points expiration policy. pending_points: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsInput' - type: 'null' description: Pending points activation policy. earning_limits: oneOf: - $ref: '#/components/schemas/CardDefinitionEarningLimitsInput' - type: 'null' description: Points earning limits. spending_limits: oneOf: - $ref: '#/components/schemas/CardDefinitionSpendingLimitsInput' - type: 'null' description: Points spending limits. refunds: oneOf: - $ref: '#/components/schemas/CardDefinitionRefundsInput' - type: 'null' description: Refund handling configuration. balance_settings: oneOf: - $ref: '#/components/schemas/CardDefinitionBalanceSettingsInput' - type: 'null' description: Card balance settings. pay_with_points: oneOf: - $ref: '#/components/schemas/CardDefinitionPayWithPointsInput' - type: 'null' description: Pay-with-points configuration. metadata: type: - object - 'null' description: Arbitrary key-value metadata attached to the card definition. additionalProperties: false CardDefinition: type: object description: A card definition. properties: id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Unique card definition ID. name: type: string description: Card definition name. type: type: string enum: - INDIVIDUAL description: Card definition type. status: type: string enum: - DRAFT - ACTIVE - DELETED description: Current card definition status. code_config: $ref: '#/components/schemas/CardDefinitionCodeConfig' points_expiration: $ref: '#/components/schemas/CardDefinitionPointsExpiration' pending_points: $ref: '#/components/schemas/CardDefinitionPendingPoints' earning_limits: $ref: '#/components/schemas/CardDefinitionEarningLimits' spending_limits: $ref: '#/components/schemas/CardDefinitionSpendingLimits' refunds: $ref: '#/components/schemas/CardDefinitionRefunds' balance_settings: $ref: '#/components/schemas/CardDefinitionBalanceSettings' pay_with_points: $ref: '#/components/schemas/CardDefinitionPayWithPoints' metadata: type: object description: Arbitrary key-value metadata. Empty object when not set. created_at: type: string format: date-time description: Creation timestamp (ISO 8601). updated_at: type: - string - 'null' format: date-time description: >- Last update timestamp (ISO 8601). Null when the card definition has never been updated. object: type: string const: card_definition description: Object type marker. Always `card_definition`. required: - id - name - type - status - code_config - points_expiration - pending_points - earning_limits - spending_limits - refunds - balance_settings - pay_with_points - metadata - created_at - updated_at - object ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Identifier of the request that produced the error. CardDefinitionCodeConfigInput: type: object description: > Card code generation configuration. When `pattern` is provided, the effective code length is the number of `#` placeholders in the pattern; otherwise `length` (default 10) `#` placeholders are used. properties: length: type: - integer - 'null' description: > Number of generated characters in the code (ignored when `pattern` is provided). A positive integer. Defaults to 10. charset: type: - string - 'null' description: >- Characters used for code generation. Defaults to alphanumeric: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`. prefix: type: - string - 'null' description: >- Fixed prefix prepended to every generated code. Defaults to an empty string. postfix: type: - string - 'null' description: >- Fixed postfix appended to every generated code. Defaults to an empty string. pattern: type: - string - 'null' description: >- Code pattern where each `#` is replaced with a random character from the charset, e.g. `###-###`. Defaults to `#` repeated `length` times. additionalProperties: false CardDefinitionPointsExpirationInput: type: object description: > Points expiration policy. Conditional requirements based on `type`: - `NO_EXPIRATION`: `rolling_expiration`, `calendar_expiration` and `sliding_expiration` must be null/absent. - `ROLLING_EXPIRATION`: `rolling_expiration` is required; the other two must be null/absent. - `CALENDAR_EXPIRATION`: `calendar_expiration` is required; the other two must be null/absent. - `SLIDING_EXPIRATION`: `sliding_expiration` is required; the other two must be null/absent. properties: type: type: string enum: - NO_EXPIRATION - ROLLING_EXPIRATION - CALENDAR_EXPIRATION - SLIDING_EXPIRATION description: Points expiration type. rolling_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationInput - type: 'null' description: >- Rolling expiration configuration. Required when `type` is `ROLLING_EXPIRATION`, must be null otherwise. calendar_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationCalendarExpirationInput - type: 'null' description: >- Calendar expiration configuration. Required when `type` is `CALENDAR_EXPIRATION`, must be null otherwise. sliding_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationSlidingExpirationInput - type: 'null' description: >- Sliding expiration configuration. Required when `type` is `SLIDING_EXPIRATION`, must be null otherwise. required: - type additionalProperties: false CardDefinitionPendingPointsInput: type: object description: > Pending points activation policy. Conditional requirements based on `type`: - `IMMEDIATE`: `period_based`, `fixed_dates` and `event_based` must be null/absent. - `PERIOD_BASED`: `period_based` is required; the other two must be null/absent. - `FIXED_DATES`: `fixed_dates` is required; the other two must be null/absent. - `EVENT_BASED`: `event_based` is required; the other two must be null/absent. properties: type: type: string enum: - IMMEDIATE - PERIOD_BASED - FIXED_DATES - EVENT_BASED description: Pending points activation type. `IMMEDIATE` means no pending period. period_based: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsPeriodBasedInput' - type: 'null' description: >- Period-based activation. Required when `type` is `PERIOD_BASED`, must be null otherwise. fixed_dates: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsFixedDatesInput' - type: 'null' description: >- Fixed-dates activation. Required when `type` is `FIXED_DATES`, must be null otherwise. event_based: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsEventBasedInput' - type: 'null' description: >- Event-based activation. Required when `type` is `EVENT_BASED`, must be null otherwise. required: - type additionalProperties: false CardDefinitionEarningLimitsInput: type: object description: Points earning limits. properties: global: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalInput' transactions: $ref: '#/components/schemas/CardDefinitionEarningLimitsTransactionsInput' required: - global - transactions additionalProperties: false CardDefinitionSpendingLimitsInput: type: object description: Points spending limits. properties: global: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalInput' transactions: $ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactionsInput' required: - global - transactions additionalProperties: false CardDefinitionRefundsInput: type: object description: Refund handling configuration. properties: spent_points: $ref: '#/components/schemas/CardDefinitionRefundsSpentPointsInput' earned_points: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsInput' required: - spent_points - earned_points additionalProperties: false CardDefinitionBalanceSettingsInput: type: object description: | Card balance settings. `allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`. properties: allow_negative: type: boolean description: Whether the card balance is allowed to go below zero. required: - allow_negative additionalProperties: false CardDefinitionPayWithPointsInput: description: | Pay-with-points configuration, discriminated by `type`: `NO_PAYMENTS` (paying with points disabled) or `EXCHANGE_RATIO` (points can be exchanged for money using a formula). oneOf: - type: object description: Paying with points is disabled. properties: type: type: string const: NO_PAYMENTS description: Pay-with-points type. required: - type additionalProperties: false - type: object description: Points can be exchanged for money at the configured ratio. properties: type: type: string const: EXCHANGE_RATIO description: Pay-with-points type. exchange_ratio: $ref: >- #/components/schemas/CardDefinitionPayWithPointsExchangeRatioInput required: - type - exchange_ratio additionalProperties: false discriminator: propertyName: type CardDefinitionCodeConfig: type: object description: >- Card code generation configuration. Always present with server-side defaults applied. properties: pattern: type: string description: >- Code pattern where each `#` is replaced with a random character from the charset. length: type: integer description: Number of `#` placeholders in the pattern. charset: type: string description: Characters used for code generation. prefix: type: string description: >- Fixed prefix prepended to every generated code. Empty string when not set. postfix: type: string description: >- Fixed postfix appended to every generated code. Empty string when not set. required: - pattern - length - charset - prefix - postfix CardDefinitionPointsExpiration: type: object description: Points expiration policy. Always present; defaults to `NO_EXPIRATION`. properties: type: type: string enum: - NO_EXPIRATION - ROLLING_EXPIRATION - CALENDAR_EXPIRATION - SLIDING_EXPIRATION description: Points expiration type. rolling_expiration: $ref: '#/components/schemas/CardDefinitionPointsExpirationRollingExpiration' description: >- Rolling expiration configuration. Only present when `type` is `ROLLING_EXPIRATION`. calendar_expiration: $ref: >- #/components/schemas/CardDefinitionPointsExpirationCalendarExpiration description: >- Calendar expiration configuration. Only present when `type` is `CALENDAR_EXPIRATION`. sliding_expiration: $ref: '#/components/schemas/CardDefinitionPointsExpirationSlidingExpiration' description: >- Sliding expiration configuration. Only present when `type` is `SLIDING_EXPIRATION`. required: - type CardDefinitionPendingPoints: type: object description: >- Pending points activation policy. Always present; defaults to `IMMEDIATE`. properties: type: type: string enum: - IMMEDIATE - PERIOD_BASED - FIXED_DATES - EVENT_BASED description: Pending points activation type. period_based: $ref: '#/components/schemas/CardDefinitionPendingPointsPeriodBased' description: Period-based activation. Only present when `type` is `PERIOD_BASED`. fixed_dates: $ref: '#/components/schemas/CardDefinitionPendingPointsFixedDates' description: Fixed-dates activation. Only present when `type` is `FIXED_DATES`. event_based: $ref: '#/components/schemas/CardDefinitionPendingPointsEventBased' description: Event-based activation. Only present when `type` is `EVENT_BASED`. required: - type CardDefinitionEarningLimits: type: object description: >- Points earning limits. Always present; defaults to `NO_LIMIT` for both scopes. properties: global: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobal' transactions: $ref: '#/components/schemas/CardDefinitionEarningLimitsTransactions' CardDefinitionSpendingLimits: type: object description: >- Points spending limits. Always present; defaults to `NO_LIMIT` for both scopes. properties: global: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobal' transactions: $ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactions' CardDefinitionRefunds: type: object description: >- Refund handling configuration. Always present; defaults to `NONE` for both scopes. properties: spent_points: $ref: '#/components/schemas/CardDefinitionRefundsSpentPoints' earned_points: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPoints' required: - spent_points - earned_points CardDefinitionBalanceSettings: type: object description: >- Card balance settings. Always present; defaults to `allow_negative: false`. properties: allow_negative: type: boolean description: Whether the card balance is allowed to go below zero. required: - allow_negative CardDefinitionPayWithPoints: type: object description: >- Pay-with-points configuration. Always present; defaults to `NO_PAYMENTS`. properties: type: type: string enum: - NO_PAYMENTS - EXCHANGE_RATIO description: Pay-with-points type. exchange_ratio: type: object description: Exchange ratio. Only present when `type` is `EXCHANGE_RATIO`. properties: formula: type: string description: Exchange ratio formula (always returned as a string). required: - formula required: - type CardDefinitionPointsExpirationRollingExpirationInput: type: object description: >- Rolling expiration configuration - points expire after a fixed period from earning. properties: period: $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationPeriodInput rounding: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationRoundingInput - type: 'null' description: Optional rounding applied to the calculated expiration date. required: - period additionalProperties: false CardDefinitionPointsExpirationCalendarExpirationInput: type: object description: >- Calendar expiration configuration - points expire on fixed calendar dates. properties: expiration_dates: type: array items: $ref: >- #/components/schemas/CardDefinitionPointsExpirationCalendarExpirationDateInput minItems: 1 maxItems: 20 description: List of calendar dates on which points expire (1-20 dates). required: - expiration_dates additionalProperties: false CardDefinitionPointsExpirationSlidingExpirationInput: type: object description: > Sliding expiration configuration - points expiration slides on member activity. 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 custom event schema IDs. properties: earning_activity: type: boolean description: Whether earning points resets the expiration window. spending_activity: type: boolean description: Whether spending points resets the expiration window. custom_activity: type: boolean description: Whether the configured custom events reset the expiration window. custom_activity_types: type: - array - 'null' items: type: string pattern: ^ms_[a-zA-Z0-9]+ maxItems: 10 description: > Custom event schema IDs (pattern `^ms_[a-zA-Z0-9]+`) that reset the expiration window. Required with 1-10 unique items when `custom_activity` is `true`. period: $ref: >- #/components/schemas/CardDefinitionPointsExpirationSlidingExpirationPeriodInput required: - period additionalProperties: false CardDefinitionPendingPointsPeriodBasedInput: type: object description: >- Period-based pending points activation - points activate after a fixed period. properties: period: $ref: >- #/components/schemas/CardDefinitionPendingPointsPeriodBasedPeriodInput required: - period additionalProperties: false CardDefinitionPendingPointsFixedDatesInput: type: object description: >- Fixed-dates pending points activation - points activate on fixed calendar dates. properties: dates: type: array items: $ref: >- #/components/schemas/CardDefinitionPendingPointsFixedDatesDateInput minItems: 1 maxItems: 20 description: >- List of calendar dates on which pending points activate (1-20 dates). required: - dates additionalProperties: false CardDefinitionPendingPointsEventBasedInput: type: object description: >- Event-based pending points activation - points activate when one of the configured custom events occurs, or are cancelled after the cancel period. properties: event_types: type: array items: type: string pattern: ^ms_[a-zA-Z0-9]+ minItems: 1 maxItems: 10 description: >- Custom event schema IDs (pattern `^ms_[a-zA-Z0-9]+`) that activate pending points. 1-10 unique items. cancel_period: $ref: >- #/components/schemas/CardDefinitionPendingPointsEventBasedCancelPeriodInput required: - event_types - cancel_period additionalProperties: false CardDefinitionEarningLimitsGlobalInput: type: object description: > Global (per card) earning limits. When `type` is `NO_LIMIT`, `limits` must be empty or null; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global earning limits apply. limits: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalLimitInput' maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionEarningLimitsTransactionsInput: type: object description: > Per-transaction earning limits. When `type` is `NO_LIMIT`, `limits` must be empty or null; when `type` is `LIMITED`, `limits` must contain at least 1 limit. Each limit `type` may appear at most once in the array. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction earning limits apply. limits: type: - array - 'null' items: $ref: >- #/components/schemas/CardDefinitionEarningLimitsTransactionsLimitInput description: >- Limit definitions with unique types. Empty/null when `type` is `NO_LIMIT`; at least 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionSpendingLimitsGlobalInput: type: object description: > Global (per card) spending limits. When `type` is `NO_LIMIT`, `limits` must be empty or null; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global spending limits apply. limits: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalLimitInput' maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionSpendingLimitsTransactionsInput: type: object description: > Per-transaction spending limits. When `type` is `NO_LIMIT`, `limits` must be empty or null; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction spending limits apply. limits: type: - array - 'null' items: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsTransactionsLimitInput maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionRefundsSpentPointsInput: type: object description: | How points spent on a refunded order are handled. When `type` is `NONE`, `methods` must be empty or null; when `type` is `REFUNDABLE`, `methods` must contain exactly 1 method. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether spent points are refundable. methods: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionRefundsSpentPointsMethodInput' maxItems: 1 description: >- Refund methods. Empty/null when `type` is `NONE`; exactly 1 item required when `type` is `REFUNDABLE`. Currently only one method is allowed. required: - type additionalProperties: false CardDefinitionRefundsEarnedPointsInput: type: object description: > How points earned on a refunded order are handled. When `type` is `NONE`, `methods` must be empty or null; when `type` is `REFUNDABLE`, `methods` must contain exactly 1 method. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether earned points are revocable on refund. methods: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsMethodInput' maxItems: 1 description: >- Revoke methods. Empty/null when `type` is `NONE`; exactly 1 item required when `type` is `REFUNDABLE`. required: - type additionalProperties: false CardDefinitionPayWithPointsExchangeRatioInput: type: object description: Exchange ratio used to convert points into money. properties: formula: oneOf: - type: string minLength: 1 maxLength: 2000 - type: number description: > Exchange ratio formula. A string expression (1-2000 characters) or a number. Numbers are converted to strings server-side. required: - formula additionalProperties: false CardDefinitionPointsExpirationRollingExpiration: type: object description: Rolling expiration configuration. properties: period: $ref: '#/components/schemas/CardDefinitionPeriod' description: Rolling expiration period. Unit is one of `DAY`, `MONTH`, `YEAR`. rounding: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationRounding - type: 'null' description: >- Rounding applied to the calculated expiration date. Null when not configured. required: - period CardDefinitionPointsExpirationCalendarExpiration: type: object description: Calendar expiration configuration. properties: expiration_dates: type: array items: $ref: '#/components/schemas/CardDefinitionCalendarDate' description: Calendar dates on which points expire. required: - expiration_dates CardDefinitionPointsExpirationSlidingExpiration: type: object description: Sliding expiration configuration. properties: earning_activity: type: boolean description: Whether earning points resets the expiration window. spending_activity: type: boolean description: Whether spending points resets the expiration window. custom_activity: type: boolean description: Whether the configured custom events reset the expiration window. custom_activity_types: type: array items: type: string description: >- Custom event schema IDs that reset the expiration window. Empty array when `custom_activity` is false. period: $ref: '#/components/schemas/CardDefinitionPeriod' description: Sliding expiration period. Unit is one of `DAY`, `MONTH`, `YEAR`. required: - custom_activity_types - period CardDefinitionPendingPointsPeriodBased: type: object description: Period-based pending points activation. properties: period: $ref: '#/components/schemas/CardDefinitionPeriod' description: Pending period. Unit is one of `DAY`, `MONTH`, `YEAR`. required: - period CardDefinitionPendingPointsFixedDates: type: object description: Fixed-dates pending points activation. properties: dates: type: array items: $ref: '#/components/schemas/CardDefinitionCalendarDate' description: Calendar dates on which pending points activate. required: - dates CardDefinitionPendingPointsEventBased: type: object description: Event-based pending points activation. properties: event_types: type: array items: type: string description: Custom event schema IDs that activate pending points. cancel_period: $ref: '#/components/schemas/CardDefinitionPeriod' description: >- Period after which non-activated pending points are cancelled. Unit is one of `DAY`, `MONTH`, `YEAR`. required: - event_types - cancel_period CardDefinitionEarningLimitsGlobal: type: object description: Global (per card) earning limits. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global earning limits apply. limits: type: array items: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalLimit' description: Limit definitions. Empty array when `type` is `NO_LIMIT`. required: - type - limits CardDefinitionEarningLimitsTransactions: type: object description: Per-transaction earning limits. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction earning limits apply. limits: type: array items: $ref: '#/components/schemas/CardDefinitionEarningLimitsTransactionsLimit' description: Limit definitions. Empty array when `type` is `NO_LIMIT`. required: - type - limits CardDefinitionSpendingLimitsGlobal: type: object description: Global (per card) spending limits. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global spending limits apply. limits: type: array items: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalLimit' description: Limit definitions. Empty array when `type` is `NO_LIMIT`. required: - type - limits CardDefinitionSpendingLimitsTransactions: type: object description: Per-transaction spending limits. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction spending limits apply. limits: type: array items: $ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactionsLimit' description: Limit definitions. Empty array when `type` is `NO_LIMIT`. required: - type - limits CardDefinitionRefundsSpentPoints: type: object description: How points spent on a refunded order are handled. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether spent points are refundable. methods: type: array items: $ref: '#/components/schemas/CardDefinitionRefundsSpentPointsMethod' description: Refund methods. Empty array when `type` is `NONE`. required: - type - methods CardDefinitionRefundsEarnedPoints: type: object description: How points earned on a refunded order are handled. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether earned points are revocable on refund. methods: type: array items: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsMethod' description: Revoke methods. Empty array when `type` is `NONE`. required: - type - methods CardDefinitionPointsExpirationRollingExpirationPeriodInput: type: object description: > Rolling expiration period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-5 for `YEAR` (enforced via if/then conditions). properties: unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 5 for `YEAR`.' required: - unit - value additionalProperties: false CardDefinitionPointsExpirationRollingExpirationRoundingInput: type: object description: > Rounding of the rolling expiration date. When `type` is `END_OF_PARTICULAR_MONTH`, `value` (month number 1-12) is required; for all other types `value` must be null/absent. properties: type: type: string enum: - END_OF_MONTH - END_OF_QUARTER - END_OF_HALF_YEAR - END_OF_YEAR - END_OF_PARTICULAR_MONTH description: Rounding type. value: type: - integer - 'null' minimum: 1 maximum: 12 description: >- Month number (1-12). Required when `type` is `END_OF_PARTICULAR_MONTH`, must be null otherwise. required: - type additionalProperties: false CardDefinitionPointsExpirationCalendarExpirationDateInput: type: object description: > A calendar date (day + month). The maximum `day` depends on `month` (enforced via if/then conditions): 29 for February, 30 for April/June/September/November, 31 for the remaining months. properties: day: type: integer minimum: 1 maximum: 31 description: >- Day of the month. Maximum depends on the month: 29 for February, 30 for April, June, September, November, 31 otherwise. month: type: integer minimum: 1 maximum: 12 description: Month number (1-12). required: - day - month additionalProperties: false CardDefinitionPointsExpirationSlidingExpirationPeriodInput: type: object description: > Sliding expiration period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. required: - value - unit additionalProperties: false CardDefinitionPendingPointsPeriodBasedPeriodInput: type: object description: > Pending period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' required: - unit - value additionalProperties: false CardDefinitionPendingPointsFixedDatesDateInput: type: object description: > A calendar date (day + month). The maximum `day` depends on `month` (enforced via if/then conditions): 29 for February, 30 for April/June/September/November, 31 for the remaining months. properties: day: type: integer minimum: 1 maximum: 31 description: >- Day of the month. Maximum depends on the month: 29 for February, 30 for April, June, September, November, 31 otherwise. month: type: integer minimum: 1 maximum: 12 description: Month number (1-12). required: - day - month additionalProperties: false CardDefinitionPendingPointsEventBasedCancelPeriodInput: type: object description: > Period after which non-activated pending points are cancelled. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. required: - value - unit additionalProperties: false CardDefinitionEarningLimitsGlobalLimitInput: description: > A global earning limit, discriminated by `type`: `BALANCE_BASED` (maximum card balance) or `TIME_BASED` (maximum points earned per period). oneOf: - type: object description: Balance-based limit - the card balance cannot exceed `max` points. properties: type: type: string const: BALANCE_BASED description: Limit type. max: type: integer minimum: 1 description: Maximum card balance in points. required: - type - max additionalProperties: false - type: object description: >- Time-based limit - at most `points.max` points can be earned per period. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedPeriodInput points: $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedPointsInput required: - type - period - points additionalProperties: false discriminator: propertyName: type CardDefinitionEarningLimitsTransactionsLimitInput: description: | A per-transaction earning limit, discriminated by `type`: `POINTS` (maximum points earned per transaction) or `SPENDING` (minimum order amount required to earn points). oneOf: - type: object description: >- Points limit - at most `max` points can be earned in a single transaction. properties: type: type: string const: POINTS description: Limit type. max: type: integer minimum: 1 description: Maximum points earned per transaction. required: - type - max additionalProperties: false - type: object description: >- Spending threshold - points are only earned when the transaction amount is at least `min_amount`. properties: type: type: string const: SPENDING description: Limit type. min_amount: type: integer minimum: 1 description: Minimum transaction amount required to earn points. required: - type - min_amount additionalProperties: false discriminator: propertyName: type CardDefinitionSpendingLimitsGlobalLimitInput: description: > A global spending limit, discriminated by `type`: `SPENDING_BASED` (total points spent) or `TIME_BASED` (points spent per period). oneOf: - type: object description: Spending-based limit - at most `max` points can be spent in total. properties: type: type: string const: SPENDING_BASED description: Limit type. max: type: integer minimum: 1 description: Maximum total points spent. required: - type - max additionalProperties: false - type: object description: >- Time-based limit - at most `points.max` points can be spent per period. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedPeriodInput points: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedPointsInput required: - type - period - points additionalProperties: false discriminator: propertyName: type CardDefinitionSpendingLimitsTransactionsLimitInput: description: >- A per-transaction spending limit. Currently only the `POINTS` type is supported. oneOf: - type: object description: >- Points limit - at most `max` points can be spent in a single transaction. properties: type: type: string const: POINTS description: Limit type. max: type: integer minimum: 1 description: Maximum points spent per transaction. required: - type - max additionalProperties: false discriminator: propertyName: type CardDefinitionRefundsSpentPointsMethodInput: description: >- A spent points refund method. Currently only the `RETURN_POINTS` type is supported. oneOf: - type: object description: Return spent points back to the card. properties: type: type: string const: RETURN_POINTS description: Refund method type. mode: type: string enum: - REFUND_ALL - REFUND_ITEM - REFUND_AMOUNT description: >- Refund mode: on full-order refund (`REFUND_ALL`), per-item refund (`REFUND_ITEM`) or amount-based refund (`REFUND_AMOUNT`). required: - type - mode additionalProperties: false discriminator: propertyName: type CardDefinitionRefundsEarnedPointsMethodInput: description: > An earned points revoke method, discriminated by `type`: `REVOKE_FROM_PENDING` (only valid when `pending_points.type` is `PERIOD_BASED`, `FIXED_DATES` or `EVENT_BASED`) or `REVOKE_FROM_BALANCE`. oneOf: - type: object description: Revoke earned points from pending points. properties: type: type: string const: REVOKE_FROM_PENDING description: Revoke method type. required: - type additionalProperties: false - type: object description: Revoke earned points from the card balance. properties: type: type: string const: REVOKE_FROM_BALANCE description: Revoke method type. mode: type: string enum: - REVOKE_TO_ZERO - REVOKE_BELOW_ZERO description: >- Revoke mode. `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative` to be `true`. required: - type - mode additionalProperties: false discriminator: propertyName: type CardDefinitionPeriod: type: object description: A period expressed as a value and unit. properties: value: type: integer description: Period length. unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. required: - value - unit CardDefinitionPointsExpirationRollingExpirationRounding: type: object description: Rounding of the rolling expiration date. properties: type: type: string enum: - END_OF_MONTH - END_OF_QUARTER - END_OF_HALF_YEAR - END_OF_YEAR - END_OF_PARTICULAR_MONTH description: Rounding type. value: type: integer minimum: 1 maximum: 12 description: >- Month number (1-12). Only present when `type` is `END_OF_PARTICULAR_MONTH`. required: - type CardDefinitionCalendarDate: type: object description: A calendar date (day + month). properties: day: type: integer minimum: 1 maximum: 31 description: Day of the month. month: type: integer minimum: 1 maximum: 12 description: Month number (1-12). required: - day - month CardDefinitionEarningLimitsGlobalLimit: description: 'A global earning limit: `BALANCE_BASED` or `TIME_BASED`.' oneOf: - type: object description: Balance-based limit. properties: type: type: string const: BALANCE_BASED description: Limit type. max: type: integer description: Maximum card balance in points. required: - type - max - type: object description: Time-based limit. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: '#/components/schemas/CardDefinitionLimitTimeBasedPeriod' points: $ref: '#/components/schemas/CardDefinitionLimitTimeBasedPoints' required: - type discriminator: propertyName: type CardDefinitionEarningLimitsTransactionsLimit: description: 'A per-transaction earning limit: `POINTS` or `SPENDING`.' oneOf: - type: object description: Points limit. properties: type: type: string const: POINTS description: Limit type. max: type: integer description: Maximum points earned per transaction. required: - type - max - type: object description: Spending threshold. properties: type: type: string const: SPENDING description: Limit type. min_amount: type: integer description: Minimum transaction amount required to earn points. required: - type - min_amount discriminator: propertyName: type CardDefinitionSpendingLimitsGlobalLimit: description: 'A global spending limit: `SPENDING_BASED` or `TIME_BASED`.' oneOf: - type: object description: Spending-based limit. properties: type: type: string const: SPENDING_BASED description: Limit type. max: type: integer description: Maximum total points spent. required: - type - max - type: object description: Time-based limit. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: '#/components/schemas/CardDefinitionLimitTimeBasedPeriod' points: $ref: '#/components/schemas/CardDefinitionLimitTimeBasedPoints' required: - type discriminator: propertyName: type CardDefinitionSpendingLimitsTransactionsLimit: type: object description: >- A per-transaction spending limit. Currently only the `POINTS` type exists. properties: type: type: string const: POINTS description: Limit type. max: type: integer description: Maximum points spent per transaction. required: - type - max CardDefinitionRefundsSpentPointsMethod: type: object description: A spent points refund method. properties: type: type: string const: RETURN_POINTS description: Refund method type. mode: type: string enum: - REFUND_ALL - REFUND_ITEM - REFUND_AMOUNT description: Refund mode. required: - type - mode CardDefinitionRefundsEarnedPointsMethod: description: >- An earned points revoke method: `REVOKE_FROM_PENDING` or `REVOKE_FROM_BALANCE`. oneOf: - type: object description: Revoke earned points from pending points. properties: type: type: string const: REVOKE_FROM_PENDING description: Revoke method type. required: - type - type: object description: Revoke earned points from the card balance. properties: type: type: string const: REVOKE_FROM_BALANCE description: Revoke method type. mode: type: string enum: - REVOKE_TO_ZERO - REVOKE_BELOW_ZERO description: Revoke mode. required: - type - mode discriminator: propertyName: type CardDefinitionEarningLimitsGlobalTimeBasedPeriodInput: type: object description: > Time-based earning limit period. When `type` is `CURRENT_PERIOD` (the only allowed value), `current_period` is required. properties: type: type: string enum: - CURRENT_PERIOD description: >- Period type. Currently only `CURRENT_PERIOD` (current calendar period) is supported. current_period: oneOf: - $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedCurrentPeriodInput - type: 'null' description: >- Current-period configuration. Required when `type` is `CURRENT_PERIOD`. required: - type additionalProperties: false CardDefinitionEarningLimitsGlobalTimeBasedPointsInput: type: object description: Points cap for the time-based earning limit. properties: max: type: integer minimum: 1 maximum: 9007199254740991 description: >- Maximum points that can be earned within the period (1 to 9007199254740991). required: - max additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedPeriodInput: type: object description: > Time-based spending limit period. When `type` is `CURRENT_PERIOD` (the only allowed value), `current_period` is required. properties: type: type: string enum: - CURRENT_PERIOD description: >- Period type. Currently only `CURRENT_PERIOD` (current calendar period) is supported. current_period: oneOf: - $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedCurrentPeriodInput - type: 'null' description: >- Current-period configuration. Required when `type` is `CURRENT_PERIOD`. required: - type additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedPointsInput: type: object description: Points cap for the time-based spending limit. properties: max: type: integer minimum: 1 maximum: 9007199254740991 description: >- Maximum points that can be spent within the period (1 to 9007199254740991). required: - max additionalProperties: false CardDefinitionLimitTimeBasedPeriod: type: object description: Time-based limit period. properties: type: type: string enum: - CURRENT_PERIOD description: Period type. current_period: type: object description: >- Current-period configuration. Present when `type` is `CURRENT_PERIOD`. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit required: - type CardDefinitionLimitTimeBasedPoints: type: object description: Points cap for a time-based limit. properties: max: type: integer description: Maximum points within the period. required: - max CardDefinitionEarningLimitsGlobalTimeBasedCurrentPeriodInput: type: object description: Calendar period unit used to reset the time-based earning limit. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedCurrentPeriodInput: type: object description: Calendar period unit used to reset the time-based spending limit. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit additionalProperties: false 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 ````