--- title: "Get benefit" method: GET path: "/v2/loyalties/benefits/{benefitId}" tags: ["Benefits"] --- # Get benefit `GET /v2/loyalties/benefits/{benefitId}` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/benefits/{benefitId}` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - HTTP bearer Returns a single benefit by its ID. ## Response `200` The benefit - V2LoyaltiesBenefitsGetResponseBody: A benefit object. Exactly one type-specific configuration object (`points`, `points_proportional`, `material`, or `digital`) is present, matching the `type`; the others are omitted. - `id` string, required: Unique benefit ID, prefixed with `lben_`. - `name` string, required: Benefit name, unique within the project. - `type` 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL', required: Benefit type. - `status` 'DRAFT' | 'ACTIVE' | 'DELETED', required: Current benefit status. `DELETED` appears only in the response of the delete endpoint and in activity snapshots. - `stock` BenefitStock, required: Stock configuration of the benefit. When `type` is `LIMITED`, the `limited` object is required. When `type` is `UNLIMITED`, requests may omit `limited` or set it to `null`; responses omit it. - `type` 'UNLIMITED' | 'LIMITED', required: Whether the benefit has unlimited or limited stock. - `limited` LoyaltyV2ActivityBenefitStockLimited: Limited stock configuration. - `quantity` integer, required: Available Remaining stock quantity. For responses, updates with each benefit purchase. - `points` LoyaltyV2ActivityBenefitPoints: Fixed points effect - adds a fixed amount of points to a card of the given card definition. - `value` integer, required: Number of points to add. - `card_definition_id` string, required: ID of the card definition whose cards receive the points. The card definition must exist and be `ACTIVE`. - `points_proportional` BenefitPointsProportional: 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`. In requests, the remaining source properties may be omitted or set to `null`. In responses, they are omitted. - `calculation_type` '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', required: 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` string, required: ID of the card definition whose cards receive the points. The card definition must exist and be ACTIVE. - `order` BenefitPointsProportionalOrder: Order-based proportional calculation. Provide the property matching the `calculation_type`. - `amount` LoyaltyV2ActivityBenefitPointsProportionalEvery: Ratio definition - `value` points for every `every` units. - `every` integer, required: Unit step (e.g. order amount in cents) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `total_amount` LoyaltyV2ActivityBenefitPointsProportionalEvery: Ratio definition - `value` points for every `every` units. - `every` integer, required: Unit step (e.g. order amount in cents) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `customer` BenefitPointsProportionalCustomer: Customer-metadata-based proportional calculation. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata, required: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `custom_event` BenefitPointsProportionalCustomEvent: Custom-event-metadata-based proportional calculation. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata, required: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `order_items` BenefitPointsProportionalOrderItems: Order-items-based proportional calculation. Provide the property matching the `calculation_type`. - `amount` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - `id` string, required: Products collection ID, prefixed with `pc_`. - `subtotal_amount` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - `id` string, required: Products collection ID, prefixed with `pc_`. - `quantity` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - `id` string, required: Products collection ID, prefixed with `pc_`. - `material` BenefitMaterial: Material benefit - a physical product or SKU. Exactly one of `product` or `sku` is required, matching the `type`. In requests, the other property may be omitted or set to `null`. In responses, it is omitted. - `type` 'PRODUCT' | 'SKU', required: Whether the benefit is a whole product or a specific SKU. - `product` LoyaltyV2ActivityBenefitMaterialProduct: Product reference for a material benefit. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` LoyaltyV2ActivityBenefitMaterialSKU: SKU reference for a material benefit. - `product_id` string, required: ID of the product the SKU belongs to, prefixed with `prod_`. - `id` string, required: SKU ID, prefixed with `sku_`. - `digital` BenefitDigital: Digital benefit - a reward sourced from a Voucherify campaign. Exactly one of `gift_vouchers` or `discount_coupons` is required, matching the `type`. In requests, the other property may be omitted or set to `null`. In responses, it is omitted. The referenced campaign must exist and its campaign type must match the benefit's digital type. - `type` 'GIFT_VOUCHERS' | 'DISCOUNT_COUPONS', required: Type of the digital reward. - `gift_vouchers` LoyaltyV2ActivityBenefitDigitalGiftVouchers: Gift vouchers digital benefit configuration. - `campaign_id` string, required: ID of the `GIFT_VOUCHERS` campaign the vouchers are sourced from, prefixed with `camp_`. - `balance` number, required: Balance loaded onto the gift voucher. - `discount_coupons` LoyaltyV2ActivityBenefitDigitalDiscountCoupons: Discount coupons digital benefit configuration. - `campaign_id` string, required: ID of the `DISCOUNT_COUPONS` campaign the coupons are sourced from, prefixed with `camp_`. - `created_at` string, date-time, required: Timestamp of when the benefit was created, in ISO 8601 format. - `updated_at` string, date-time, nullable, required: Timestamp of the last update, in ISO 8601 format. `null` when the benefit was never updated. - `object` 'benefit', required: Type of the object. Always `benefit`. ## Other responses - `404`: The benefit doesn't exist. A deleted benefit is not found. Returned for any unknown benefit id, including a value that does not match `lben_[a-f0-9]+`. `key` is `not_found` and `resource_type` is `benefit`. - `500`: Internal server error. ## Changes - **2026-10-14** (v2) `ec801ade260d`: 1 warning - deleted the `path` request parameter `benefitId` - **2026-10-13** (v2) `f95b50556c93`: 1 breaking - added the new path request parameter `benefitId` - **2026-10-13** (v2) `9905dfce1d1e`: 1 warning - deleted the `path` request parameter `benefitId` - **2026-10-13** (v2) `c59a345c733b`: 1 breaking - added the new path request parameter `benefitId` - **2026-10-13** (v2) `4d4d694f1847`: 1 warning - deleted the `path` request parameter `benefitId` [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/benefits/:benefitId/get.md) --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)