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 with the specified configuration.

Required fields: name, type. All other fields have sensible defaults. The code_config is optional on input but required internally (defaults are generated).

Custom validators applied:

• createCardDefinitionBalanceSettings: balance_settings.allow_negative can only be true when points_expiration.type is NO_EXPIRATION.
• createCardDefinitionRefunds: refunds.earned_points.methods with type REVOKE_BELOW_ZERO requires balance_settings.allow_negative: true. Method type REVOKE_FROM_PENDING requires pending_points.type to be one of PERIOD_BASED, FIXED_DATES, or EVENT_BASED.

POST /v2/loyalties/card-definitions

Create Card Definition

cURL

curl --request POST \
  --url https://api.voucherify.io/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",
  "status": "DRAFT",
  "code_config": {
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>",
    "pattern": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 2
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 2
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "type": "POINTS",
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {
          "type": "RETURN_POINTS"
        }
      ]
    },
    "earned_points": {
      "methods": [
        {}
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {}
}
'

200

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

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

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<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

name · string · required

Required string length: 1 - 200

type · enum<string> · required

Available options: INDIVIDUAL

status · enum<string> | null · default: DRAFT

Initial status. Defaults to DRAFT if not provided.

Available options: DRAFT, ACTIVE, null

code_config · object | null

Code generation configuration. Defaults to 10-character alphanumeric pattern if not provided.

Show child attributes

points_expiration · object | null

Points expiration policy. Defaults to NO_EXPIRATION.

Show child attributes

pending_points · object | null

Pending points policy. Defaults to IMMEDIATE.

Show child attributes

earning_limits · object | null

Earning limits configuration. Defaults to no limits.

Show child attributes

spending_limits · object | null

Spending limits configuration. Defaults to no limits.

Show child attributes

refunds · object | null

Refund policies. Defaults to no refunds.

Show child attributes

balance_settings · object | null

Balance settings. Defaults to allow_negative: false.

Show child attributes

metadata · object | null

Response

200

application/json

Created card definition

Full card definition DTO returned by all CRUD endpoints.

id · string · required

name · string · required

type · enum<string> · required

Available options: INDIVIDUAL

status · enum<string> · required

Available options: DRAFT, ACTIVE, INACTIVE, DELETED

code_config · object · required

Show child attributes

points_expiration · object · required

Show child attributes

pending_points · object · required

Show child attributes

earning_limits · object · required

Show child attributes

spending_limits · object · required

Show child attributes

refunds · object · required

Show child attributes

balance_settings · object · required

Show child attributes

metadata · object · required

created_at · string<date-time> · required

object · string · required

Allowed value: "card_definition"

updated_at · string<date-time> | null