> ## 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. # Move benefit to draft > ⚠️ **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. Moves a benefit from `ACTIVE` back to `DRAFT` status. No request body. Only the `ACTIVE` -> `DRAFT` transition is allowed; drafting from any other state returns 400 `invalid_state_transition`. A benefit assigned to an active earning rule cannot be moved to draft (423 `resource_locked`, key `connected_active_earning_rule`). ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/benefits/{benefitId}/draft 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/benefits/{benefitId}/draft: post: tags: - Benefits summary: Move benefit to draft 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. Moves a benefit from `ACTIVE` back to `DRAFT` status. No request body. Only the `ACTIVE` -> `DRAFT` transition is allowed; drafting from any other state returns 400 `invalid_state_transition`. A benefit assigned to an active earning rule cannot be moved to draft (423 `resource_locked`, key `connected_active_earning_rule`). operationId: draftBenefit parameters: - name: id in: path required: true description: Unique benefit ID, prefixed with `lben_`. schema: type: string pattern: ^lben_[a-f0-9]+$ responses: '200': description: The drafted benefit content: application/json: schema: $ref: '#/components/schemas/Benefit' '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' '423': description: >- Resource locked - a related resource is in a state that prevents this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Benefit: type: object description: > A benefit object. Exactly one type-specific configuration object (`points`, `points_proportional`, `material`, or `digital`) is present, matching the `type`; the others are omitted. properties: id: type: string pattern: ^lben_[a-f0-9]+$ description: Unique benefit ID, prefixed with `lben_`. name: type: string description: Benefit name, unique within the project. type: type: string enum: - POINTS - POINTS_PROPORTIONAL - MATERIAL - DIGITAL description: Benefit type. status: type: string enum: - DRAFT - ACTIVE - DELETED description: >- Current benefit status. `DELETED` appears only in the response of the delete endpoint and in activity snapshots. stock: description: Stock configuration. Omitted when not set. oneOf: - $ref: '#/components/schemas/BenefitStock' points: description: Fixed points configuration. Present only when `type` is `POINTS`. oneOf: - $ref: '#/components/schemas/BenefitPoints' points_proportional: description: >- Proportional points configuration. Present only when `type` is `POINTS_PROPORTIONAL`. oneOf: - $ref: '#/components/schemas/BenefitPointsProportional' material: description: Material configuration. Present only when `type` is `MATERIAL`. oneOf: - $ref: '#/components/schemas/BenefitMaterial' digital: description: Digital configuration. Present only when `type` is `DIGITAL`. oneOf: - $ref: '#/components/schemas/BenefitDigital' created_at: type: string format: date-time description: Timestamp of when the benefit was created, in ISO 8601 format. updated_at: type: - string - 'null' format: date-time description: >- Timestamp of the last update, in ISO 8601 format. Null when the benefit was never updated. object: type: string const: benefit description: Type of the object. Always `benefit`. required: - id - name - type - status - 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. BenefitStock: type: object description: > Stock configuration of the benefit. When `type` is `LIMITED` the `limited` object is required; when `type` is `UNLIMITED` the `limited` object must be omitted or null. properties: type: type: string enum: - UNLIMITED - LIMITED description: Whether the benefit has unlimited or limited stock. limited: description: >- Limited stock configuration. Required when `type` is `LIMITED`, must be null otherwise. oneOf: - $ref: '#/components/schemas/BenefitStockLimited' - type: 'null' required: - type additionalProperties: false allOf: - if: properties: type: const: UNLIMITED then: properties: limited: type: 'null' - if: properties: type: const: LIMITED then: required: - limited properties: limited: $ref: '#/components/schemas/BenefitStockLimited' BenefitPoints: type: object description: >- Fixed points effect - adds a fixed amount of points to a card of the given card definition. properties: value: type: integer minimum: 0 maximum: 9007199254740991 description: Number of points to add. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: >- ID of the card definition whose cards receive the points. The card definition must exist and be ACTIVE. required: - value - card_definition_id additionalProperties: false BenefitPointsProportional: type: object description: > Proportional points effect - points are calculated from an order amount, order items, or a metadata property. Exactly one calculation source object (`order`, `customer`, `custom_event`, or `order_items`) is required, determined by `calculation_type`; the remaining source properties must be omitted or null. properties: calculation_type: type: string enum: - PRE_DISCOUNT_ORDER_AMOUNT - POST_DISCOUNT_ORDER_AMOUNT - PRE_DISCOUNT_ORDER_ITEMS_AMOUNT - POST_DISCOUNT_ORDER_ITEMS_AMOUNT - ORDER_ITEMS_QUANTITY - ORDER_METADATA_VALUE - CUSTOMER_METADATA_VALUE - CUSTOM_EVENT_METADATA_VALUE description: > How the points are calculated: - `PRE_DISCOUNT_ORDER_AMOUNT` - points per every specified order amount before discounts (requires `order.amount`) - `POST_DISCOUNT_ORDER_AMOUNT` - points per every specified order amount after discounts (requires `order.total_amount`) - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT` - points per every specified amount spent on selected products before discounts (requires `order_items.amount`) - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT` - points per every specified amount spent on selected products after discounts (requires `order_items.subtotal_amount`) - `ORDER_ITEMS_QUANTITY` - points per every specified quantity of selected products, excluding free items (requires `order_items.quantity`) - `ORDER_METADATA_VALUE` - points per every specified value in the order metadata (requires `order.metadata`) - `CUSTOMER_METADATA_VALUE` - points per every specified value in the customer metadata (requires `customer.metadata`) - `CUSTOM_EVENT_METADATA_VALUE` - points per every specified value in the custom event metadata (requires `custom_event.metadata`) card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: >- ID of the card definition whose cards receive the points. The card definition must exist and be ACTIVE. order: description: >- Order-based calculation configuration (for `PRE_DISCOUNT_ORDER_AMOUNT`, `POST_DISCOUNT_ORDER_AMOUNT`, `ORDER_METADATA_VALUE`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalOrder' - type: 'null' customer: description: >- Customer-metadata-based calculation configuration (for `CUSTOMER_METADATA_VALUE`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalCustomer' - type: 'null' custom_event: description: >- Custom-event-metadata-based calculation configuration (for `CUSTOM_EVENT_METADATA_VALUE`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalCustomEvent' - type: 'null' order_items: description: >- Order-items-based calculation configuration (for `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`, `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`, `ORDER_ITEMS_QUANTITY`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalOrderItems' - type: 'null' required: - calculation_type - card_definition_id additionalProperties: false allOf: - if: properties: calculation_type: const: PRE_DISCOUNT_ORDER_AMOUNT then: required: - order properties: order: type: object required: - amount customer: type: 'null' custom_event: type: 'null' order_items: type: 'null' - if: properties: calculation_type: const: POST_DISCOUNT_ORDER_AMOUNT then: required: - order properties: order: type: object required: - total_amount customer: type: 'null' custom_event: type: 'null' order_items: type: 'null' - if: properties: calculation_type: const: ORDER_METADATA_VALUE then: required: - order properties: order: type: object required: - metadata customer: type: 'null' custom_event: type: 'null' order_items: type: 'null' - if: properties: calculation_type: const: CUSTOMER_METADATA_VALUE then: required: - customer properties: customer: $ref: '#/components/schemas/BenefitPointsProportionalCustomer' order: type: 'null' custom_event: type: 'null' order_items: type: 'null' - if: properties: calculation_type: const: CUSTOM_EVENT_METADATA_VALUE then: required: - custom_event properties: custom_event: $ref: '#/components/schemas/BenefitPointsProportionalCustomEvent' order: type: 'null' customer: type: 'null' order_items: type: 'null' - if: properties: calculation_type: const: PRE_DISCOUNT_ORDER_ITEMS_AMOUNT then: required: - order_items properties: order_items: type: object required: - amount order: type: 'null' customer: type: 'null' custom_event: type: 'null' - if: properties: calculation_type: const: POST_DISCOUNT_ORDER_ITEMS_AMOUNT then: required: - order_items properties: order_items: type: object required: - subtotal_amount order: type: 'null' customer: type: 'null' custom_event: type: 'null' - if: properties: calculation_type: const: ORDER_ITEMS_QUANTITY then: required: - order_items properties: order_items: type: object required: - quantity order: type: 'null' customer: type: 'null' custom_event: type: 'null' BenefitMaterial: type: object description: > Material benefit - a physical product or SKU. Exactly one of `product` or `sku` is required, matching the `type`; the other must be omitted or null. properties: type: type: string enum: - PRODUCT - SKU description: Whether the benefit is a whole product or a specific SKU. product: description: >- Product reference. Required when `type` is `PRODUCT`, must be null otherwise. The product must exist. oneOf: - $ref: '#/components/schemas/BenefitMaterialProduct' - type: 'null' sku: description: >- SKU reference. Required when `type` is `SKU`, must be null otherwise. The SKU must exist under the given product. oneOf: - $ref: '#/components/schemas/BenefitMaterialSKU' - type: 'null' additionalProperties: false allOf: - required: - type - if: properties: type: const: PRODUCT then: required: - product properties: product: $ref: '#/components/schemas/BenefitMaterialProduct' sku: type: 'null' - if: properties: type: const: SKU then: required: - sku properties: sku: $ref: '#/components/schemas/BenefitMaterialSKU' product: type: 'null' BenefitDigital: type: object description: > Digital benefit - a reward sourced from a Voucherify campaign. Exactly one of `gift_vouchers` or `discount_coupons` is required, matching the `type`; the other must be omitted or null. The referenced campaign must exist and its campaign type must match the benefit's digital type. properties: type: type: string enum: - GIFT_VOUCHERS - DISCOUNT_COUPONS description: Type of the digital reward. gift_vouchers: description: >- Gift vouchers configuration. Required when `type` is `GIFT_VOUCHERS`, must be null otherwise. oneOf: - $ref: '#/components/schemas/BenefitDigitalGiftVouchers' - type: 'null' discount_coupons: description: >- Discount coupons configuration. Required when `type` is `DISCOUNT_COUPONS`, must be null otherwise. oneOf: - $ref: '#/components/schemas/BenefitDigitalDiscountCoupons' - type: 'null' additionalProperties: false allOf: - required: - type - if: properties: type: const: DISCOUNT_COUPONS then: required: - discount_coupons properties: discount_coupons: $ref: '#/components/schemas/BenefitDigitalDiscountCoupons' gift_vouchers: type: 'null' - if: properties: type: const: GIFT_VOUCHERS then: required: - gift_vouchers properties: gift_vouchers: $ref: '#/components/schemas/BenefitDigitalGiftVouchers' discount_coupons: type: 'null' BenefitStockLimited: type: object description: Limited stock configuration. properties: quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Remaining stock quantity. required: - quantity additionalProperties: false BenefitPointsProportionalOrder: type: object description: >- Order-based proportional calculation. Provide the property matching the `calculation_type`. properties: amount: description: >- Points per every specified pre-discount order amount (for `PRE_DISCOUNT_ORDER_AMOUNT`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalEvery' total_amount: description: >- Points per every specified post-discount order amount (for `POST_DISCOUNT_ORDER_AMOUNT`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalEvery' metadata: description: >- Points per every specified value of an order metadata property (for `ORDER_METADATA_VALUE`). oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalMetadata' additionalProperties: false BenefitPointsProportionalCustomer: type: object description: Customer-metadata-based proportional calculation. properties: metadata: description: Points per every specified value of a customer metadata property. oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalMetadata' required: - metadata additionalProperties: false BenefitPointsProportionalCustomEvent: type: object description: Custom-event-metadata-based proportional calculation. properties: metadata: description: >- Points per every specified value of a custom event metadata property. oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalMetadata' required: - metadata additionalProperties: false BenefitPointsProportionalOrderItems: type: object description: >- Order-items-based proportional calculation. Provide the property matching the `calculation_type`. properties: amount: description: >- Points per every specified pre-discount amount spent on the selected items (for `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`). oneOf: - $ref: >- #/components/schemas/BenefitPointsProportionalOrderItemsCalculation subtotal_amount: description: >- Points per every specified post-discount amount spent on the selected items (for `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`). oneOf: - $ref: >- #/components/schemas/BenefitPointsProportionalOrderItemsCalculation quantity: description: >- Points per every specified quantity of the selected items, excluding free items (for `ORDER_ITEMS_QUANTITY`). oneOf: - $ref: >- #/components/schemas/BenefitPointsProportionalOrderItemsCalculation additionalProperties: false BenefitMaterialProduct: type: object description: Product reference for a material benefit. properties: id: type: string pattern: ^prod_[a-f0-9]+ description: Product ID, prefixed with `prod_`. required: - id additionalProperties: false BenefitMaterialSKU: type: object description: SKU reference for a material benefit. properties: product_id: type: string pattern: ^prod_[a-f0-9]+ description: ID of the product the SKU belongs to, prefixed with `prod_`. id: type: string pattern: ^sku_[a-f0-9]+ description: SKU ID, prefixed with `sku_`. required: - product_id - id additionalProperties: false BenefitDigitalGiftVouchers: type: object description: Gift vouchers digital benefit configuration. properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: >- ID of the GIFT_VOUCHERS campaign the vouchers are sourced from, prefixed with `camp_`. balance: type: number minimum: 0 maximum: 9007199254740991 description: Balance loaded onto the gift voucher. required: - campaign_id - balance additionalProperties: false BenefitDigitalDiscountCoupons: type: object description: Discount coupons digital benefit configuration. properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: >- ID of the DISCOUNT_COUPONS campaign the coupons are sourced from, prefixed with `camp_`. required: - campaign_id additionalProperties: false BenefitPointsProportionalEvery: type: object description: Ratio definition - `value` points for every `every` units. properties: every: type: integer minimum: 1 maximum: 9007199254740991 description: >- Unit step (e.g. order amount in cents) for which `value` points are granted. value: type: number minimum: 0 maximum: 9007199254740991 description: Number of points granted per `every` units. required: - every - value additionalProperties: false BenefitPointsProportionalMetadata: type: object description: >- Metadata-based ratio definition - `value` points for every `every` units of the metadata property. properties: every: type: integer minimum: 1 maximum: 9007199254740991 description: >- Unit step of the metadata property value for which `value` points are granted. value: type: number minimum: 0 maximum: 9007199254740991 description: Number of points granted per `every` units. property: type: string minLength: 1 description: Name of the metadata property used for the calculation. required: - every - value - property additionalProperties: false BenefitPointsProportionalOrderItemsCalculation: type: object description: >- Order-items ratio definition with the list of applicable products/SKUs/collections. properties: every: type: integer minimum: 1 maximum: 9007199254740991 description: Unit step (amount or quantity) for which `value` points are granted. value: type: number minimum: 0 maximum: 9007199254740991 description: Number of points granted per `every` units. applicable_to: type: array minItems: 1 description: Products, SKUs, or product collections the calculation applies to. items: $ref: '#/components/schemas/BenefitPointsProportionalApplicableTo' required: - every - value - applicable_to additionalProperties: false BenefitPointsProportionalApplicableTo: type: object description: > A single applicability rule. Exactly one of `product`, `sku`, or `products_collection` is required, matching the `type`; the other two must be omitted or null. properties: type: type: string enum: - product - sku - products_collection description: Type of the referenced object. product: description: >- Product reference. Required when `type` is `product`, must be null otherwise. oneOf: - $ref: >- #/components/schemas/BenefitPointsProportionalApplicableToProduct - type: 'null' sku: description: >- SKU reference. Required when `type` is `sku`, must be null otherwise. oneOf: - $ref: '#/components/schemas/BenefitPointsProportionalApplicableToSku' - type: 'null' products_collection: description: >- Products collection reference. Required when `type` is `products_collection`, must be null otherwise. oneOf: - $ref: >- #/components/schemas/BenefitPointsProportionalApplicableToProductsCollection - type: 'null' required: - type additionalProperties: false allOf: - if: properties: type: const: product then: required: - product properties: product: $ref: >- #/components/schemas/BenefitPointsProportionalApplicableToProduct sku: type: 'null' products_collection: type: 'null' - if: properties: type: const: sku then: required: - sku properties: sku: $ref: '#/components/schemas/BenefitPointsProportionalApplicableToSku' product: type: 'null' products_collection: type: 'null' - if: properties: type: const: products_collection then: required: - products_collection properties: products_collection: $ref: >- #/components/schemas/BenefitPointsProportionalApplicableToProductsCollection product: type: 'null' sku: type: 'null' BenefitPointsProportionalApplicableToProduct: type: object description: Product reference. properties: id: type: string pattern: ^prod_[a-f0-9]+ description: Product ID, prefixed with `prod_`. required: - id additionalProperties: false BenefitPointsProportionalApplicableToSku: type: object description: SKU reference. properties: id: type: string pattern: ^sku_[a-f0-9]+ description: SKU ID, prefixed with `sku_`. required: - id additionalProperties: false BenefitPointsProportionalApplicableToProductsCollection: type: object description: Products collection reference. properties: id: type: string pattern: ^pc_[a-zA-Z0-9]+ description: Products collection ID, prefixed with `pc_`. required: - id additionalProperties: false 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 ````