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>"
}

Create 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.

Creates a new card definition. Only name and type are required; all other sections default server-side as follows:

code_config: 10-character alphanumeric code pattern (##########)
points_expiration: NO_EXPIRATION
pending_points: IMMEDIATE
earning_limits: global NO_LIMIT, transactions NO_LIMIT
spending_limits: global NO_LIMIT, transactions NO_LIMIT
refunds: spent points NONE, earned points NONE
balance_settings: allow_negative: false
pay_with_points: NO_PAYMENTS

Cross-field rules:

balance_settings.allow_negative can only be true when points_expiration.type is NO_EXPIRATION. Additionally, the earned points refund mode REVOKE_BELOW_ZERO requires balance_settings.allow_negative to be true.
The earned points refund method REVOKE_FROM_PENDING requires pending_points.type to be one of PERIOD_BASED, FIXED_DATES, EVENT_BASED.

POST

loyalties

card-definitions

Create Card Definition

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/card-definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "INDIVIDUAL",
  "code_config": {
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>",
    "pattern": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 45
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 45
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 45
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 45
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "type": "<string>",
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "<string>",
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    },
    "earned_points": {
      "methods": [
        {
          "type": "<string>"
        }
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "pay_with_points": {
    "type": "<string>"
  },
  "metadata": {}
}
'

{
  "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

Body

application/json

Request body for creating a card definition. Cross-field rules apply: balance_settings.allow_negative: true requires points_expiration.type to be NO_EXPIRATION; the earned points refund mode REVOKE_BELOW_ZERO requires allow_negative: true; and the earned points refund method REVOKE_FROM_PENDING requires pending_points.type to be PERIOD_BASED, FIXED_DATES or EVENT_BASED.

name

string

required

Card definition name.

Required string length: 1 - 200

type

enum<string>

required

Card definition type. Currently only INDIVIDUAL is supported.

Available options:

INDIVIDUAL

status

enum<string> | null

Initial status. Allowed values on create are DRAFT and ACTIVE. Defaults to DRAFT when omitted.

Available options:

DRAFT,

ACTIVE,

null

code_config

object | null

Card code generation configuration. Defaults to a 10-character alphanumeric pattern.

Show child attributes

points_expiration

object | null

Points expiration policy. Defaults to NO_EXPIRATION.

Show child attributes

pending_points

object | null

Pending points activation policy. Defaults to IMMEDIATE.

Show child attributes

earning_limits

object | null

Points earning limits. Defaults to NO_LIMIT for both global and transaction limits.

Show child attributes

spending_limits

object | null

Points spending limits. Defaults to NO_LIMIT for both global and transaction limits.

Show child attributes

refunds

object | null

Refund handling configuration. Defaults to NONE for both spent and earned points.

Show child attributes

balance_settings

object | null

Card balance settings. Defaults to allow_negative: false.

Show child attributes

pay_with_points

object

Pay-with-points configuration. Defaults to NO_PAYMENTS.

Option 1
Option 2

Show child attributes

metadata

object | null

Arbitrary key-value metadata attached to the card definition.

Response

The created 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

List Card Definitions Get Card Definition

⌘I