> ## 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. # Activate an incentive > ⚠️ **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. Transitions an incentive from DRAFT to ACTIVE. The only valid transition is DRAFT -> ACTIVE. Connected card definitions must exist and be ACTIVE. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/incentives/{id}/activate openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete API documentation for Voucherify Loyalty v2 system. Requires LOYALTY_V2 feature flag. servers: - url: https://api.voucherify.io description: Production security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - 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: 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: 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: Incentives description: >- Manage incentive 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: Examines the earning of loyalty points for a loyalty program member. paths: /v2/loyalties/incentives/{id}/activate: post: tags: - Incentives summary: Activate an incentive 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. Transitions an incentive from DRAFT to ACTIVE. The only valid transition is DRAFT -> ACTIVE. Connected card definitions must exist and be ACTIVE. operationId: activateIncentive parameters: - $ref: '#/components/parameters/IncentiveId' responses: '200': description: The activated incentive. content: application/json: schema: $ref: '#/components/schemas/IncentiveDTO' '400': $ref: '#/components/responses/InvalidStateTransition' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: IncentiveId: name: id in: path required: true description: 'Unique incentive identifier (prefix: `linc_`).' schema: type: string pattern: ^linc_[a-f0-9]+$ example: linc_abc123def456 schemas: IncentiveDTO: type: object description: Incentive response object. properties: id: type: string pattern: ^linc_[a-f0-9]+$ description: Unique incentive identifier. example: linc_abc123def456 name: type: string maxLength: 200 description: Human-readable name. type: $ref: '#/components/schemas/IncentiveType' status: $ref: '#/components/schemas/IncentiveStatus' stock: type: integer minimum: 0 maximum: 2147483647 description: Remaining stock count. points: $ref: '#/components/schemas/IncentivePointsDTO' points_proportional: $ref: '#/components/schemas/IncentivePointsProportionalDTO' material: $ref: '#/components/schemas/IncentiveMaterialDTO' digital: $ref: '#/components/schemas/IncentiveDigitalDTO' created_at: type: string format: date-time description: ISO 8601 creation timestamp. updated_at: type: - string - 'null' format: date-time description: ISO 8601 last-update timestamp, or null if never updated. object: type: string const: incentive description: Object type discriminator. required: - id - name - type - status - stock - created_at - object IncentiveType: type: string enum: - POINTS - POINTS_PROPORTIONAL - MATERIAL - DIGITAL description: > Type of incentive. Determines which detail object is present in the response and required in create/update requests. IncentiveStatus: type: string enum: - DRAFT - ACTIVE - DELETED description: Current lifecycle status of the incentive. IncentivePointsDTO: type: object description: Fixed-points incentive configuration. properties: value: type: integer minimum: 0 maximum: 9223372036854776000 description: Number of points to award. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Card definition to which points are added. required: - value - card_definition_id IncentivePointsProportionalDTO: type: object description: > Proportional-points incentive configuration. The `calculation_type` determines which sub-object is required: - `PRE_DISCOUNT_ORDER_AMOUNT` -> `order.amount` - `POST_DISCOUNT_ORDER_AMOUNT` -> `order.total_amount` - `ORDER_METADATA_VALUE` -> `order.metadata` - `CUSTOMER_METADATA_VALUE` -> `customer.metadata` - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT` -> `order_items.amount` - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT` -> `order_items.subtotal_amount` - `ORDER_ITEMS_QUANTITY` -> `order_items.quantity` properties: calculation_type: $ref: '#/components/schemas/PointsProportionalCalculationType' card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Card definition to which points are added. order: $ref: '#/components/schemas/IncentivePointsProportionalOrder' customer: $ref: '#/components/schemas/IncentivePointsProportionalCustomer' order_items: $ref: '#/components/schemas/IncentivePointsProportionalOrderItems' required: - calculation_type - card_definition_id IncentiveMaterialDTO: type: object description: > Material incentive configuration. Exactly one of `product` or `sku` must be provided based on `type`. properties: type: $ref: '#/components/schemas/IncentiveMaterialType' product: oneOf: - $ref: '#/components/schemas/IncentiveMaterialProductDTO' - type: 'null' sku: oneOf: - $ref: '#/components/schemas/IncentiveMaterialSkuDTO' - type: 'null' required: - type IncentiveDigitalDTO: type: object description: > Digital incentive configuration. Exactly one of `discount_coupons` or `gift_vouchers` must be provided based on `type`. properties: type: $ref: '#/components/schemas/IncentiveDigitalType' discount_coupons: oneOf: - $ref: '#/components/schemas/IncentiveDigitalDiscountCouponsDTO' - type: 'null' gift_vouchers: oneOf: - $ref: '#/components/schemas/IncentiveDigitalGiftVouchersDTO' - type: 'null' required: - type ErrorResponse: type: object description: Standard error response. properties: code: type: integer description: HTTP status code. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional error details. request_id: type: - string - 'null' description: Request identifier for tracing. resource_id: type: string description: Related resource identifier (when applicable). resource_type: type: string description: Related resource type (when applicable). required: - code - key - message PointsProportionalCalculationType: 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 description: > Calculation type for proportional points. Determines which sub-object (`order`, `customer`, `order_items`) is required. IncentivePointsProportionalOrder: type: object description: Order-level proportional calculation config. properties: amount: $ref: '#/components/schemas/IncentivePointsProportionalEvery' total_amount: $ref: '#/components/schemas/IncentivePointsProportionalEvery' metadata: $ref: '#/components/schemas/IncentivePointsProportionalMetadata' additionalProperties: false IncentivePointsProportionalCustomer: type: object description: Customer-level proportional calculation config. properties: metadata: $ref: '#/components/schemas/IncentivePointsProportionalMetadata' required: - metadata additionalProperties: false IncentivePointsProportionalOrderItems: type: object description: Order-items-level proportional calculation config. properties: amount: $ref: >- #/components/schemas/IncentivePointsProportionalOrderItemsCalculation subtotal_amount: $ref: >- #/components/schemas/IncentivePointsProportionalOrderItemsCalculation quantity: $ref: >- #/components/schemas/IncentivePointsProportionalOrderItemsCalculation additionalProperties: false IncentiveMaterialType: type: string enum: - PRODUCT - SKU IncentiveMaterialProductDTO: type: object properties: id: type: string pattern: ^prod_[a-f0-9]+ description: Product identifier. required: - id additionalProperties: false IncentiveMaterialSkuDTO: type: object properties: product_id: type: string pattern: ^prod_[a-f0-9]+ description: Parent product identifier. id: type: string pattern: ^sku_[a-f0-9]+ description: SKU identifier. required: - product_id - id additionalProperties: false IncentiveDigitalType: type: string enum: - GIFT_VOUCHERS - DISCOUNT_COUPONS IncentiveDigitalDiscountCouponsDTO: type: object properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: ID of a DISCOUNT_COUPONS campaign. required: - campaign_id additionalProperties: false IncentiveDigitalGiftVouchersDTO: type: object properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: ID of a GIFT_VOUCHERS campaign. balance: type: number minimum: 0 maximum: 9223372036854776000 description: Initial balance to set on the gift voucher. required: - campaign_id - balance additionalProperties: false IncentivePointsProportionalEvery: type: object properties: every: type: integer minimum: 1 maximum: 9223372036854776000 description: For every `every` units of the base metric. value: type: integer minimum: 0 maximum: 9223372036854776000 description: Award `value` points. required: - every - value additionalProperties: false IncentivePointsProportionalMetadata: type: object properties: every: type: integer minimum: 1 maximum: 9223372036854776000 value: type: integer minimum: 0 maximum: 9223372036854776000 property: type: string minLength: 1 description: Metadata property key to read the value from. required: - every - value - property additionalProperties: false IncentivePointsProportionalOrderItemsCalculation: type: object properties: every: type: integer minimum: 1 maximum: 9223372036854776000 value: type: integer minimum: 0 maximum: 9223372036854776000 applicable_to: type: array items: $ref: '#/components/schemas/IncentivePointsProportionalApplicableTo' minItems: 1 required: - every - value - applicable_to additionalProperties: false IncentivePointsProportionalApplicableTo: type: object description: > Identifies a product, SKU, or products collection that the calculation applies to. Exactly one of `product`, `sku`, or `products_collection` must be provided based on `type`. properties: type: $ref: '#/components/schemas/PointsProportionalApplicableToObjectType' product: $ref: '#/components/schemas/IncentivePointsProportionalApplicableToProduct' sku: $ref: '#/components/schemas/IncentivePointsProportionalApplicableToSku' products_collection: $ref: >- #/components/schemas/IncentivePointsProportionalApplicableToProductsCollection required: - type additionalProperties: false PointsProportionalApplicableToObjectType: type: string enum: - product - sku - products_collection IncentivePointsProportionalApplicableToProduct: type: object properties: id: type: string pattern: ^prod_[a-f0-9]+ required: - id additionalProperties: false IncentivePointsProportionalApplicableToSku: type: object properties: id: type: string pattern: ^sku_[a-f0-9]+ required: - id additionalProperties: false IncentivePointsProportionalApplicableToProductsCollection: type: object properties: id: type: string pattern: ^pc_[a-zA-Z0-9]+ required: - id additionalProperties: false responses: InvalidStateTransition: description: The requested state transition is not valid from the current state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 400 key: invalid_state_transition message: Invalid state transition details: 'Cannot activate incentive from current state: ''ACTIVE''' request_id: v-abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 ````