Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "name": "<string>",
  "type": "INDIVIDUAL",
  "code_config": {
    "pattern": "<string>",
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 123
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 123
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 123
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 123
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    },
    "earned_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "pay_with_points": {
    "exchange_ratio": {
      "formula": "<string>"
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

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.

PUT

loyalties

card-definitions

{cardDefinitionId}

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "name": "<string>",
  "type": "INDIVIDUAL",
  "code_config": {
    "pattern": "<string>",
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 123
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 123
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 123
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 123
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 123
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    },
    "earned_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "pay_with_points": {
    "exchange_ratio": {
      "formula": "<string>"
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Path Parameters

string

required

Unique card definition ID. Pattern: ^lcdef_[a-f0-9]+$.

Pattern: ^lcdef_[a-f0-9]+$

Body

application/json

Request body for updating a card definition. All properties are optional. type and status cannot be updated.

name

string | null

Card definition name.

Required string length: 1 - 200

code_config

object | null

Card code generation configuration.

Show child attributes

points_expiration

object | null

Points expiration policy.

Show child attributes

pending_points

object | null

Pending points activation policy.

Show child attributes

earning_limits

object | null

Points earning limits.

Show child attributes

spending_limits

object | null

Points spending limits.

Show child attributes

refunds

object | null

Refund handling configuration.

Show child attributes

balance_settings

object | null

Card balance settings.

Show child attributes

pay_with_points

object

Pay-with-points configuration.

Option 1
Option 2

Show child attributes

metadata

object | null

Arbitrary key-value metadata attached to the card definition.

Response

The updated card definition.

A card definition.

string

required

Unique card definition ID.

Pattern: ^lcdef_[a-f0-9]+$

name

string

required

Card definition name.

type

enum<string>

required

Card definition type.

Available options:

INDIVIDUAL

status

enum<string>

required

Current card definition status.

Available options:

DRAFT,

ACTIVE,

DELETED

code_config

object

required

Card code generation configuration. Always present with server-side defaults applied.

Show child attributes

points_expiration

object

required

Points expiration policy. Always present; defaults to NO_EXPIRATION.

Show child attributes

pending_points

object

required

Pending points activation policy. Always present; defaults to IMMEDIATE.

Show child attributes

earning_limits

object

required

Points earning limits. Always present; defaults to NO_LIMIT for both scopes.

Show child attributes

spending_limits

object

required

Points spending limits. Always present; defaults to NO_LIMIT for both scopes.

Show child attributes

refunds

object

required

Refund handling configuration. Always present; defaults to NONE for both scopes.

Show child attributes

balance_settings

object

required

Card balance settings. Always present; defaults to allow_negative: false.

Show child attributes

pay_with_points

object

required

Pay-with-points configuration. Always present; defaults to NO_PAYMENTS.

Show child attributes

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> | null

required

Last update timestamp (ISO 8601). Null when the card definition has never been updated.

object

string

required

Object type marker. Always card_definition.

Allowed value: "card_definition"

Last modified on July 10, 2026

Get Card Definition Delete Card Definition

⌘I