--- 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: none required 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](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single benefit by its ID. ## Path parameters - `id` string, required ## Response `200` The benefit - Benefit: 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: 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. - `type` 'UNLIMITED' | 'LIMITED', required: Whether the benefit has unlimited or limited stock. - `limited` BenefitStockLimited: Limited stock configuration. - `quantity` integer, required: Remaining stock quantity. - `points` BenefitPoints: 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`; the remaining source properties must be omitted or null. - `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` BenefitPointsProportionalEvery: 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` BenefitPointsProportionalEvery: 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` BenefitPointsProportionalMetadata: 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` BenefitPointsProportionalMetadata, 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` BenefitPointsProportionalMetadata, 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` BenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` BenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` BenefitPointsProportionalApplicableToProductsCollection: 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` BenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` BenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` BenefitPointsProportionalApplicableToProductsCollection: 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` BenefitPointsProportionalApplicableToProduct: Product reference. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` BenefitPointsProportionalApplicableToSku: SKU reference. - `id` string, required: SKU ID, prefixed with `sku_`. - `products_collection` BenefitPointsProportionalApplicableToProductsCollection: 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`; the other must be omitted or null. - `type` 'PRODUCT' | 'SKU', required: Whether the benefit is a whole product or a specific SKU. - `product` BenefitMaterialProduct: Product reference for a material benefit. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` BenefitMaterialSKU: 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`; the other must be omitted or null. 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` BenefitDigitalGiftVouchers: 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` BenefitDigitalDiscountCoupons: 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: Timestamp of the last update, in ISO 8601 format. Null when the benefit was never updated. - `object` string, required: Type of the object. Always `benefit`. ## Other responses - `400`: Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. - `404`: Resource not found. - `409`: Conflict - e.g. duplicate resource or invalid state transition. - `500`: Internal server error. --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/revisions/4982266e0494?raw)