> ## 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. # 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 subject to change. If you want to share feedback or improvements, contact Voucherify 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: - 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/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 subject to change. If you want to share feedback or improvements, contact Voucherify 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: Identifier of the request 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: 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: >- 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: >- 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: >- 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: >- 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: 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: 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: 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: >- 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: >- Identifier of the card definition the points are spent from, prefixed with `lcdef_`. required: - points - card_definition_id 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 ````