> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a reward
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be 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.
Creates a new reward. `name`, `type` and `costs` are required. When `type` is
`MATERIAL` the `material` object is required and `digital` must be null; when
`type` is `DIGITAL` the `digital` object is required and `material` must be null.
The reward can be created directly in `DRAFT` (default) or `ACTIVE` status.
When `validity_hours` is not provided it defaults to `{ "type": "ANY_TIME" }`.
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/rewards
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:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
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),
membership retrieval (member + program + cards with tier progress, by
customer ID, customer source ID, or member ID), 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/rewards:
post:
tags:
- Rewards
summary: Create a reward
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 be
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.
Creates a new reward. `name`, `type` and `costs` are required. When
`type` is
`MATERIAL` the `material` object is required and `digital` must be null;
when
`type` is `DIGITAL` the `digital` object is required and `material` must
be null.
The reward can be created directly in `DRAFT` (default) or `ACTIVE`
status.
When `validity_hours` is not provided it defaults to `{ "type":
"ANY_TIME" }`.
operationId: createReward
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RewardCreateRequest'
responses:
'200':
description: The created reward.
content:
application/json:
schema:
$ref: '#/components/schemas/RewardResponse'
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - e.g. duplicate resource or 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:
RewardCreateRequest:
type: object
description: >-
Request body for creating a reward.
When `type` is `MATERIAL`, `material` is required and
`digital` must be null; when `type` is `DIGITAL`, `digital` is required
and
`material` must be null.
properties:
name:
type: string
minLength: 1
maxLength: 200
description: Display name of the reward.
type:
type: string
enum:
- MATERIAL
- DIGITAL
description: >-
Reward type. MATERIAL rewards deliver a product or SKU; DIGITAL
rewards deliver discount coupons, gift vouchers or loyalty card
points.
status:
type: string
enum:
- DRAFT
- ACTIVE
description: >-
Initial status of the reward. Defaults to DRAFT behavior when
omitted.
validity_hours:
description: >-
Hours during which the reward can be purchased. Defaults to `{
"type": "ANY_TIME" }` when omitted or `null`.
oneOf:
- $ref: '#/components/schemas/RewardValidityHoursRequest'
- type: 'null'
start_date:
type:
- string
- 'null'
format: date-time
description: >-
Date from which the reward is available. Must be an ISO-8601
compliant date.
end_date:
type:
- string
- 'null'
format: date-time
description: >-
Date until which the reward is available. Must be an ISO-8601
compliant date.
material:
description: >-
Material reward definition. Required when `type` is MATERIAL; must
be null when `type` is DIGITAL.
oneOf:
- $ref: '#/components/schemas/RewardMaterialRequest'
- type: 'null'
digital:
description: >-
Digital reward definition. Required when `type` is DIGITAL; must be
null when `type` is MATERIAL.
oneOf:
- $ref: '#/components/schemas/RewardDigitalRequest'
- type: 'null'
costs:
type: array
minItems: 1
maxItems: 10
description: >-
Point costs of the reward. Each cost defines the points to spend on
a specific card definition, optionally guarded by rules.
items:
$ref: '#/components/schemas/RewardCostCreateRequest'
refunds:
description: >-
Refund policy for the reward. Defaults to `{ "type": "NONE" }` when
omitted.
oneOf:
- $ref: '#/components/schemas/RewardRefundsRequest'
- type: 'null'
metadata:
type:
- object
- 'null'
description: >-
Arbitrary key-value metadata attached to the reward, as a free-form
object.
required:
- name
- type
- costs
additionalProperties: false
RewardResponse:
type: object
description: A reward, as returned by the API.
properties:
id:
type: string
pattern: ^lrew_[a-f0-9]+$
description: Unique reward identifier, prefixed with `lrew_`.
name:
type: string
description: Display name of the reward.
type:
type: string
enum:
- MATERIAL
- DIGITAL
description: Reward type.
status:
type: string
enum:
- ACTIVE
- DRAFT
- INACTIVE
- DELETED
description: Current lifecycle status of the reward.
start_date:
type:
- string
- 'null'
format: date-time
description: Date from which the reward is available, or `null` when not set.
end_date:
type:
- string
- 'null'
format: date-time
description: Date until which the reward is available, or `null` when not set.
validity_hours:
$ref: '#/components/schemas/RewardValidityHoursResponse'
description: >-
Hours during which the reward can be purchased. Always present;
defaults to `{ "type": "ANY_TIME" }`.
material:
$ref: '#/components/schemas/RewardMaterialResponse'
description: >-
Material reward definition. Present only when `type` is MATERIAL;
omitted otherwise.
digital:
$ref: '#/components/schemas/RewardDigitalResponse'
description: >-
Digital reward definition. Present only when `type` is DIGITAL;
omitted otherwise.
refunds:
$ref: '#/components/schemas/RewardRefundsResponse'
description: 'Refund policy. Always present; defaults to `{ "type": "NONE" }`.'
costs:
type: array
description: Point costs of the reward. Empty array when no costs are defined.
items:
$ref: '#/components/schemas/RewardCostResponse'
metadata:
type: object
description: >-
Arbitrary key-value metadata attached to the reward. Empty object
when not set.
created_at:
type: string
format: date-time
description: Timestamp when the reward was created (ISO-8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: >-
Timestamp when the reward was last updated (ISO-8601), or `null`
when never updated.
object:
type: string
const: reward
description: Object type marker; always `reward`.
required:
- id
- name
- type
- status
- validity_hours
- refunds
- costs
- metadata
- created_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: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
RewardValidityHoursRequest:
type: object
description: >-
Validity hours definition. `type` is
required. When `type` is `ANY_TIME`, `daily` must be null; when `type`
is `DAILY`,
`daily` is required and must contain at least one entry.
properties:
type:
type: string
enum:
- DAILY
- ANY_TIME
description: >-
Whether the reward is purchasable at any time or only during
specific daily windows.
daily:
description: >-
Daily time windows. Required when `type` is DAILY; must be null when
`type` is ANY_TIME.
oneOf:
- type: array
minItems: 1
items:
$ref: '#/components/schemas/RewardValidityDailyHoursRequest'
- type: 'null'
required:
- type
additionalProperties: false
RewardMaterialRequest:
type: object
description: >-
Material reward definition.
`type` is required. When `type` is `PRODUCT`, `product` is required and
`sku` must
be null; when `type` is `SKU`, `sku` is required and `product` must be
null.
properties:
type:
type: string
enum:
- PRODUCT
- SKU
description: Kind of material reward.
product:
description: >-
Product delivered by the reward. Required when `type` is PRODUCT;
must be null when `type` is SKU.
oneOf:
- $ref: '#/components/schemas/RewardMaterialProductRequest'
- type: 'null'
sku:
description: >-
SKU delivered by the reward. Required when `type` is SKU; must be
null when `type` is PRODUCT.
oneOf:
- $ref: '#/components/schemas/RewardMaterialSKURequest'
- type: 'null'
required:
- type
additionalProperties: false
RewardDigitalRequest:
type: object
description: >-
Digital reward definition. `type` is
required. Exactly the object matching `type` is required and the other
two must be
null: `DISCOUNT_COUPONS` requires `discount_coupons`, `GIFT_VOUCHERS`
requires
`gift_vouchers`, `LOYALTY_CARD_POINTS` requires `loyalty_card_points`.
properties:
type:
type: string
enum:
- DISCOUNT_COUPONS
- GIFT_VOUCHERS
- LOYALTY_CARD_POINTS
description: Kind of digital reward.
discount_coupons:
description: >-
Discount coupons configuration. Required when `type` is
DISCOUNT_COUPONS; must be null otherwise.
oneOf:
- $ref: '#/components/schemas/RewardDigitalDiscountCouponsRequest'
- type: 'null'
gift_vouchers:
description: >-
Gift vouchers configuration. Required when `type` is GIFT_VOUCHERS;
must be null otherwise.
oneOf:
- $ref: '#/components/schemas/RewardDigitalGiftVouchersRequest'
- type: 'null'
loyalty_card_points:
description: >-
Loyalty card points configuration. Required when `type` is
LOYALTY_CARD_POINTS; must be null otherwise.
oneOf:
- $ref: '#/components/schemas/RewardDigitalLoyaltyCardPointsRequest'
- type: 'null'
required:
- type
additionalProperties: false
RewardCostCreateRequest:
type: object
description: >-
A reward cost for creation. `spending`
is required. `rules`, when provided, must have between 1 and 10
properties (in
addition to the constraints of the rules object itself).
properties:
rules:
$ref: '#/components/schemas/RewardCostRulesRequest'
description: >-
Rules guarding this cost. Only members matching the rules can
purchase the reward at this cost. Must have between 1 and 10
properties.
spending:
type: array
minItems: 1
maxItems: 1
description: >-
Points to spend on a specific card definition. Exactly one entry is
allowed.
items:
$ref: '#/components/schemas/RewardCostSpendingRequest'
required:
- spending
additionalProperties: false
RewardRefundsRequest:
type: object
description: Refund policy for the reward.
properties:
type:
type: string
enum:
- NONE
- REFUNDABLE
description: Whether reward purchases can be refunded.
required:
- type
additionalProperties: false
RewardValidityHoursResponse:
type: object
description: >-
Validity hours. `daily` is present only when `type` is DAILY; omitted
otherwise.
properties:
type:
type: string
enum:
- DAILY
- ANY_TIME
description: >-
Whether the reward is purchasable at any time or only during
specific daily windows.
daily:
type: array
description: Daily time windows. Present only when `type` is DAILY.
items:
$ref: '#/components/schemas/RewardValidityDailyHoursResponse'
required:
- type
RewardMaterialResponse:
type: object
description: Material reward definition.
properties:
type:
type: string
enum:
- PRODUCT
- SKU
description: Kind of material reward.
product:
$ref: '#/components/schemas/RewardMaterialProductResponse'
description: >-
Product delivered by the reward. Present only when `type` is
PRODUCT; omitted otherwise.
sku:
$ref: '#/components/schemas/RewardMaterialSKUResponse'
description: >-
SKU delivered by the reward. Present only when `type` is SKU;
omitted otherwise.
required:
- type
RewardDigitalResponse:
type: object
description: >-
Digital reward definition. Only the object matching `type` is present;
the others are omitted.
properties:
type:
type: string
enum:
- DISCOUNT_COUPONS
- GIFT_VOUCHERS
- LOYALTY_CARD_POINTS
description: Kind of digital reward.
discount_coupons:
$ref: '#/components/schemas/RewardDigitalDiscountCouponsResponse'
description: >-
Discount coupons configuration. Present only when `type` is
DISCOUNT_COUPONS.
gift_vouchers:
$ref: '#/components/schemas/RewardDigitalGiftVouchersResponse'
description: >-
Gift vouchers configuration. Present only when `type` is
GIFT_VOUCHERS.
loyalty_card_points:
$ref: '#/components/schemas/RewardDigitalLoyaltyCardPointsResponse'
description: >-
Loyalty card points configuration. Present only when `type` is
LOYALTY_CARD_POINTS.
required:
- type
RewardRefundsResponse:
type: object
description: Refund policy.
properties:
type:
type: string
enum:
- NONE
- REFUNDABLE
description: Whether reward purchases can be refunded. Defaults to NONE.
required:
- type
RewardCostResponse:
type: object
description: |-
A reward cost. `rules` is omitted when the cost has no
rule definitions; `spending` is null when no spending is defined.
properties:
id:
type: string
pattern: ^lrcst_[a-f0-9]+$
description: Unique cost identifier, prefixed with `lrcst_`.
rules:
$ref: '#/components/schemas/RewardCostRuleGroupResponse'
description: >-
Rules guarding this cost. Omitted when the cost has no rule
definitions.
spending:
type:
- array
- 'null'
description: Points spending definitions, or `null` when none are defined.
items:
$ref: '#/components/schemas/RewardCostSpendingResponse'
required:
- id
RewardValidityDailyHoursRequest:
type: object
description: A single daily validity window.
properties:
days_of_week:
type: array
minItems: 1
maxItems: 7
description: >-
Days of the week the window applies to, as integers 0-6 (0 =
Sunday). Values must be unique.
items:
type: integer
minimum: 0
maximum: 6
start_time:
type: string
description: Window start time in `HH:mm` format.
example: '09:00'
end_time:
type: string
description: Window end time in `HH:mm` format.
example: '17:00'
required:
- days_of_week
- start_time
- end_time
additionalProperties: false
RewardMaterialProductRequest:
type: object
description: Product reference for a material reward.
properties:
id:
type: string
pattern: ^prod_[a-f0-9]+
description: Product identifier, prefixed with `prod_`.
required:
- id
additionalProperties: false
RewardMaterialSKURequest:
type: object
description: SKU reference for a material reward.
properties:
product_id:
type: string
pattern: ^prod_[a-f0-9]+
description: >-
Unique identifier of the product the SKU belongs to, prefixed with
`prod_`.
id:
type: string
pattern: ^sku_[a-f0-9]+
description: SKU identifier, prefixed with `sku_`.
required:
- product_id
- id
additionalProperties: false
RewardDigitalDiscountCouponsRequest:
type: object
description: Discount coupons digital reward configuration.
properties:
campaign_id:
type: string
pattern: ^camp_[a-zA-Z0-9]+
description: >-
Unique identifier of the discount coupons campaign to publish a
coupon from, prefixed with `camp_`.
required:
- campaign_id
additionalProperties: false
RewardDigitalGiftVouchersRequest:
type: object
description: Gift vouchers digital reward configuration.
properties:
campaign_id:
type: string
pattern: ^camp_[a-zA-Z0-9]+
description: >-
Unique identifier of the gift vouchers campaign to publish a voucher
from, prefixed with `camp_`.
balance:
type: number
minimum: 0
description: Gift card balance credited when the reward is delivered.
required:
- campaign_id
- balance
additionalProperties: false
RewardDigitalLoyaltyCardPointsRequest:
type: object
description: Loyalty card points digital reward configuration.
properties:
points:
type: integer
minimum: 1
maximum: 9007199254740991
description: >-
Number of points credited to the member's card when the reward is
delivered.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition to credit points to,
prefixed with `lcdef_`.
required:
- points
- card_definition_id
additionalProperties: false
RewardCostRulesRequest:
type: object
description: >-
Rules group for a reward cost. Contains a required `logic` property plus
numbered
rule definitions. Every property other than `logic` must be a
positive-integer
key (`^[1-9]\d*$`) mapping to a rule definition. At least one rule
definition is
required. No other properties are allowed.
properties:
logic:
type: string
description: >-
A logical formula referencing the numbered rule definitions, e.g.
`"1 AND 2"`.
patternProperties:
^[1-9]\d*$:
$ref: '#/components/schemas/RewardCostRuleDefinitionRequest'
required:
- logic
minProperties: 2
additionalProperties: false
RewardCostSpendingRequest:
type: object
description: Points spending definition for a cost.
properties:
points:
type: integer
minimum: 1
maximum: 9007199254740991
description: Number of points the member must spend.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition the points are spent from,
prefixed with `lcdef_`.
required:
- points
- card_definition_id
additionalProperties: false
RewardValidityDailyHoursResponse:
type: object
description: A single daily validity window.
properties:
days_of_week:
type: array
description: >-
Days of the week the window applies to, as integers 0-6 (0 =
Sunday).
items:
type: integer
minimum: 0
maximum: 6
start_time:
type: string
description: Window start time in `HH:mm` format.
example: '09:00'
end_time:
type: string
description: Window end time in `HH:mm` format.
example: '17:00'
required:
- days_of_week
- start_time
- end_time
RewardMaterialProductResponse:
type: object
description: Product reference.
properties:
id:
type: string
pattern: ^prod_[a-f0-9]+
description: Product identifier, prefixed with `prod_`.
required:
- id
RewardMaterialSKUResponse:
type: object
description: SKU reference.
properties:
product_id:
type: string
pattern: ^prod_[a-f0-9]+
description: >-
Unique identifier of the product the SKU belongs to, prefixed with
`prod_`.
id:
type: string
pattern: ^sku_[a-f0-9]+
description: SKU identifier, prefixed with `sku_`.
required:
- product_id
- id
RewardDigitalDiscountCouponsResponse:
type: object
description: Discount coupons configuration.
properties:
campaign_id:
type: string
pattern: ^camp_[a-zA-Z0-9]+
description: >-
Unique identifier of the discount coupons campaign, prefixed with
`camp_`.
required:
- campaign_id
RewardDigitalGiftVouchersResponse:
type: object
description: Gift vouchers configuration.
properties:
campaign_id:
type: string
pattern: ^camp_[a-zA-Z0-9]+
description: >-
Unique identifier of the gift vouchers campaign, prefixed with
`camp_`.
balance:
type: number
description: Gift card balance credited when the reward is delivered.
required:
- campaign_id
- balance
RewardDigitalLoyaltyCardPointsResponse:
type: object
description: Loyalty card points configuration.
properties:
points:
type: integer
description: Number of points credited when the reward is delivered.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition points are credited to,
prefixed with `lcdef_`.
required:
- points
- card_definition_id
RewardCostRuleGroupResponse:
type: object
description: |-
Rules group. Contains a `logic` formula string plus
numbered rule definition properties (positive-integer keys).
properties:
logic:
type: string
description: >-
Logical formula combining the numbered rule definitions, e.g. `"1
AND 2"`.
patternProperties:
^[1-9]\d*$:
$ref: '#/components/schemas/RewardCostRuleDefinitionResponse'
RewardCostSpendingResponse:
type: object
description: Points spending definition.
properties:
points:
type: integer
description: Number of points the member must spend.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition the points are spent from,
prefixed with `lcdef_`.
required:
- points
- card_definition_id
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````