> ## 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.

# List benefits

> 
<Info>

<Badge color="gray">Documentation in progress</Badge>

This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.

</Info>

Returns a cursor-paginated list of benefits. Supports filtering by `id`, `name`, `status`,
`type`, and `created_at`, ordering by `created_at`, `name`, and `type` (prefix with `-` for
descending), and cursor-based pagination. Deleted benefits are excluded.
Multiple filters are combined with the `junction` (`AND` by default).
The same field cannot be ordered both ascending and descending at the same time.

A successful call records no activity.



## OpenAPI

````yaml /openapi/loyalties-v2.json get /v2/loyalties/benefits
openapi: 3.1.0
info:
  title: Voucherify API - Loyalty v2
  version: v2018-08-01
  description: >-
    Voucherify promotion engine REST API. Please see
    https://docs.voucherify.io/docs for more details.
  contact:
    name: Voucherify Team
    url: https://www.voucherify.io/contact-support
    email: support@voucherify.io
  termsOfService: https://www.voucherify.io/legal/subscription-agreement
  license:
    name: MIT
    url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE
servers:
  - url: https://{cluster}.voucherify.io
    description: Base URL
    variables:
      cluster:
        default: api
        enum:
          - api
          - us1.api
          - as1.api
          - download
          - us1.download
          - as1.download
security: []
paths:
  /v2/loyalties/benefits:
    get:
      tags:
        - Benefits
      summary: List benefits
      description: >-

        <Info>


        <Badge color="gray">Documentation in progress</Badge>


        This documentation is in progress. The parameters, fields, request and
        response bodies, and other data may be subject to change. If you need
        more information or you want to share feedback, contact [Voucherify
        support](https://www.voucherify.io/contact-support) or your Technical
        Account Manager.


        </Info>


        Returns a cursor-paginated list of benefits. Supports filtering by `id`,
        `name`, `status`,

        `type`, and `created_at`, ordering by `created_at`, `name`, and `type`
        (prefix with `-` for

        descending), and cursor-based pagination. Deleted benefits are excluded.

        Multiple filters are combined with the `junction` (`AND` by default).

        The same field cannot be ordered both ascending and descending at the
        same time.


        A successful call records no activity.
      operationId: listBenefits
      parameters:
        - name: limit
          in: query
          required: false
          description: >-
            Limits the page size to an integer from 1 to 100. Defaults to 10. A
            numeric string is accepted and rounded to the nearest integer.
          schema:
            type:
              - number
              - string
              - 'null'
            minimum: 1
            maximum: 100
            default: 10
        - name: order
          in: query
          required: false
          description: >-
            Orders the results. Accepts one value or an array. Prefix a field
            with `-` for descending order. Defaults to `-created_at`. The same
            field cannot be used in both directions. Rows with the same sort
            value are then ordered by `id` ascending.
          schema:
            oneOf:
              - type: array
                items:
                  type: string
                  enum:
                    - '-created_at'
                    - created_at
                    - name
                    - '-name'
                    - '-type'
                    - type
              - type: string
                enum:
                  - '-created_at'
                  - created_at
                  - name
                  - '-name'
                  - '-type'
                  - type
              - type: 'null'
        - name: cursor
          in: query
          required: false
          description: >-
            Continues pagination. Pass the `cursor.next` value from a previous
            response. Format `lcrsben_[a-f0-9]+`. The cursor matches the filters
            and order of that response.
          schema:
            type:
              - string
              - 'null'
            pattern: ^lcrsben_[a-f0-9]+$
        - name: filters
          in: query
          required: false
          style: deepObject
          explode: true
          description: >-
            Filters the results. Pass a deep object, for example
            `filters[name][conditions][$contains]=gold`. Fields combine through
            `junction`, which defaults to `AND`. Omit `filters` to apply no
            field filter.
          schema:
            oneOf:
              - $ref: '#/components/schemas/LoyaltiesBenefitsListRequestQuery'
              - type: 'null'
      responses:
        '200':
          description: Cursor-paginated list of benefits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2LoyaltiesBenefitsListResponseBody'
        '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'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal server error:
                  value:
                    code: 500
                    key: api_error
                    message: >-
                      Something went wrong. Don't worry, your campaigns are
                      still safe and the Voucherify Team has been notified.
                      Check out our Help Center and forums for help, or head
                      back to home.
      security:
        - X-App-Id: []
          X-App-Token: []
        - bearerAuth: []
components:
  schemas:
    LoyaltiesBenefitsListRequestQuery:
      type: object
      description: Request query schema for **GET** `/v2/loyalties/benefits`.
      properties:
        junction:
          description: >-
            Joins the field filters. Allowed values are `AND` and `OR`. Defaults
            to `AND`.
          oneOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
        id:
          description: >-
            Filter by benefit ID.

            Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Values must
            match `^lben_[a-f0-9]+$`.

            `$is`/`$is_not` accept a single value (string or 1-element array);
            `$in`/`$not_in`

            accept up to 100 values.
          oneOf:
            - $ref: '#/components/schemas/LoyaltiesBenefitsListRequestQueryId'
            - type: 'null'
        name:
          description: >-
            Filter by benefit name.

            Allowed conditions: `$is`, `$is_not`, `$contains`, `$not_contain`,
            `$starts_with`,

            `$ends_with`, `$in`, `$not_in`, `$has_value`, `$is_unknown`.
            `$in`/`$not_in` accept

            up to 10 values; the other value conditions accept a single value
            (string or

            1-element array); `$has_value`/`$is_unknown` are presence checks.
          oneOf:
            - $ref: '#/components/schemas/LoyaltiesBenefitsListRequestQueryName'
            - type: 'null'
        status:
          description: >-
            Filter by benefit status.

            Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed
            values: `ACTIVE`, `DRAFT`.
          oneOf:
            - $ref: '#/components/schemas/LoyaltiesBenefitsListRequestQueryStatus'
            - type: 'null'
        type:
          description: >-
            Filter by benefit type.

            Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed
            values: `POINTS`,

            `POINTS_PROPORTIONAL`, `MATERIAL`, `DIGITAL`.
          oneOf:
            - $ref: '#/components/schemas/LoyaltiesBenefitsListRequestQueryType'
            - type: 'null'
        created_at:
          description: >-
            Filter by creation date.

            Allowed conditions: `$before`, `$after` (ISO 8601 date-time
            strings), `$is`,

            `$more_than`, `$less_than` (non-negative integers, number of days),
            `$has_value`,

            `$is_unknown` (presence checks).
          oneOf:
            - $ref: '#/components/schemas/BenefitDateFilterConditions'
            - type: 'null'
      additionalProperties: false
      title: Loyalties Benefits List Request Query
    V2LoyaltiesBenefitsListResponseBody:
      title: V2 Loyalties Benefits List Response Body
      type: object
      description: Response body schema for **GET** `/v2/loyalties/benefits`.
      allOf:
        - $ref: '#/components/schemas/BenefitListResponse'
    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: Unique identifier of the request that produced the error.
        resource_id:
          type: string
          description: Unique identifier of the resource that produced the error.
        resource_type:
          type: string
          description: Type of the resource that produced the error.
    LoyaltiesBenefitsListRequestQueryId:
      type: object
      description: >-
        ID conditions. Format `lben_[a-f0-9]+`. At least one condition is
        required.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: >-
                Matches one value. A string or a one-element array. Format
                `lben_[a-f0-9]+`.
              oneOf:
                - type: string
                  pattern: ^lben_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lben_[a-f0-9]+$
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: >-
                Excludes one value. A string or a one-element array. Format
                `lben_[a-f0-9]+`.
              oneOf:
                - type: string
                  pattern: ^lben_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lben_[a-f0-9]+$
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: >-
                Matches any of the values. A string or an array of 1 to 100
                values. Format `lben_[a-f0-9]+`.
              oneOf:
                - type: string
                  pattern: ^lben_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lben_[a-f0-9]+$
                  minItems: 1
                  maxItems: 100
                - type: 'null'
            $not_in:
              description: >-
                Excludes any of the values. A string or an array of 1 to 100
                values. Format `lben_[a-f0-9]+`.
              oneOf:
                - type: string
                  pattern: ^lben_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lben_[a-f0-9]+$
                  minItems: 1
                  maxItems: 100
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    LoyaltiesBenefitsListRequestQueryName:
      type: object
      description: String conditions. At least one condition is required.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Matches one value. A string or a one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: Excludes one value. A string or a one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $contains:
              description: >-
                Matches when the value contains the substring. A string or a
                one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $not_contain:
              description: >-
                Excludes values that contain the substring. A string or a
                one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $starts_with:
              description: >-
                Matches when the value starts with the prefix. A string or a
                one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $ends_with:
              description: >-
                Matches when the value ends with the suffix. A string or a
                one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: >-
                Matches any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $not_in:
              description: >-
                Excludes any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $has_value:
              description: Matches when the field is set. The condition value is ignored.
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
            $is_unknown:
              description: >-
                Matches when the field is not set. The condition value is
                ignored.
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    LoyaltiesBenefitsListRequestQueryStatus:
      type: object
      description: Enum conditions. At least one condition is required.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Matches one value. A string or a one-element array.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: Excludes one value. A string or a one-element array.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: >-
                Matches any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $not_in:
              description: >-
                Excludes any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 10
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    LoyaltiesBenefitsListRequestQueryType:
      type: object
      description: Enum conditions. At least one condition is required.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Matches one value. A string or a one-element array.
              oneOf:
                - type: string
                  enum:
                    - POINTS
                    - POINTS_PROPORTIONAL
                    - MATERIAL
                    - DIGITAL
                - type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    type: string
                    enum:
                      - POINTS
                      - POINTS_PROPORTIONAL
                      - MATERIAL
                      - DIGITAL
                - type: 'null'
            $is_not:
              description: Excludes one value. A string or a one-element array.
              oneOf:
                - type: string
                  enum:
                    - POINTS
                    - POINTS_PROPORTIONAL
                    - MATERIAL
                    - DIGITAL
                - type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    type: string
                    enum:
                      - POINTS
                      - POINTS_PROPORTIONAL
                      - MATERIAL
                      - DIGITAL
                - type: 'null'
            $in:
              description: >-
                Matches any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                  enum:
                    - POINTS
                    - POINTS_PROPORTIONAL
                    - MATERIAL
                    - DIGITAL
                - type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    enum:
                      - POINTS
                      - POINTS_PROPORTIONAL
                      - MATERIAL
                      - DIGITAL
                - type: 'null'
            $not_in:
              description: >-
                Excludes any of the values. A string or an array of 1 to 10
                values.
              oneOf:
                - type: string
                  enum:
                    - POINTS
                    - POINTS_PROPORTIONAL
                    - MATERIAL
                    - DIGITAL
                - type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    enum:
                      - POINTS
                      - POINTS_PROPORTIONAL
                      - MATERIAL
                      - DIGITAL
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    BenefitDateFilterConditions:
      type: object
      description: Date conditions. At least one condition is required.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $before:
              description: >-
                Matches dates before the given value. An ISO 8601 date-time, as
                a string or a one-element array.
              oneOf:
                - type: string
                  format: date-time
                - type: array
                  items:
                    type: string
                    format: date-time
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $after:
              description: >-
                Matches dates after the given value. An ISO 8601 date-time, as a
                string or a one-element array.
              oneOf:
                - type: string
                  format: date-time
                - type: array
                  items:
                    type: string
                    format: date-time
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is:
              description: >-
                Matches a date exactly the given number of days ago. A
                non-negative integer, as a string or a one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $more_than:
              description: >-
                Matches dates more than the given number of days ago. A
                non-negative integer, as a string or a one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $less_than:
              description: >-
                Matches dates less than the given number of days ago. A
                non-negative integer, as a string or a one-element array.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $has_value:
              description: Matches when the field is set. The condition value is ignored.
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
            $is_unknown:
              description: >-
                Matches when the field is not set. The condition value is
                ignored.
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    BenefitListResponse:
      type: object
      description: Cursor-paginated list of benefits.
      properties:
        data:
          type: array
          description: Benefits matching the query, in the requested order.
          items:
            $ref: '#/components/schemas/Benefit'
        cursor:
          description: Pagination cursor. `null` when there are no more results.
          oneOf:
            - $ref: '#/components/schemas/BenefitListCursor'
            - type: 'null'
        object:
          type: string
          const: list
          description: Type of the object. Always `list`.
      required:
        - data
        - cursor
        - object
    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. Always present. Null stock is returned as
            `UNLIMITED` with `limited` omitted.
          oneOf:
            - $ref: '#/components/schemas/BenefitStock'
        points:
          description: Fixed points configuration. Present only when `type` is `POINTS`.
          oneOf:
            - $ref: '#/components/schemas/LoyaltyV2ActivityBenefitPoints'
        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
        - stock
        - created_at
        - updated_at
        - object
    BenefitListCursor:
      type: object
      description: Pagination cursor pointing to the next page of results.
      properties:
        next:
          type: string
          description: >-
            Cursor ID to pass as the `cursor` query parameter to fetch the next
            page.
        expires_at:
          type: string
          format: date-time
          description: Timestamp after which the cursor expires.
      required:
        - next
    BenefitStock:
      type: object
      description: >-
        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.
      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`. When
            `type` is `UNLIMITED`, requests may omit it or set it to `null`;
            responses omit it.
          oneOf:
            - $ref: '#/components/schemas/LoyaltyV2ActivityBenefitStockLimited'
            - 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/LoyaltyV2ActivityBenefitStockLimited'
    LoyaltyV2ActivityBenefitPoints:
      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`. In requests, the remaining
        source properties may be omitted or set to `null`. In responses, they
        are omitted.
      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. Required for
            `PRE_DISCOUNT_ORDER_AMOUNT`, `POST_DISCOUNT_ORDER_AMOUNT`, and
            `ORDER_METADATA_VALUE`. For other calculation types, requests may
            omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: '#/components/schemas/BenefitPointsProportionalOrder'
            - type: 'null'
        customer:
          description: >-
            Customer-metadata-based calculation configuration. Required for
            `CUSTOMER_METADATA_VALUE`. For other calculation types, requests may
            omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: '#/components/schemas/BenefitPointsProportionalCustomer'
            - type: 'null'
        custom_event:
          description: >-
            Custom-event-metadata-based calculation configuration. Required for
            `CUSTOM_EVENT_METADATA_VALUE`. For other calculation types, requests
            may omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: '#/components/schemas/BenefitPointsProportionalCustomEvent'
            - type: 'null'
        order_items:
          description: >-
            Order-items-based calculation configuration. Required for
            `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`,
            `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`, and `ORDER_ITEMS_QUANTITY`. For
            other calculation types, requests may omit it or set it to `null`;
            responses omit it.
          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`. In requests, the other
        property may be omitted or set to `null`. In responses, it is omitted.
      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`. When `type` is
            `SKU`, requests may omit it or set it to `null`; responses omit it.
            The product must exist.
          oneOf:
            - $ref: '#/components/schemas/LoyaltyV2ActivityBenefitMaterialProduct'
            - type: 'null'
        sku:
          description: >-
            SKU reference. Required when `type` is `SKU`. When `type` is
            `PRODUCT`, requests may omit it or set it to `null`; responses omit
            it. The SKU must exist under the given product.
          oneOf:
            - $ref: '#/components/schemas/LoyaltyV2ActivityBenefitMaterialSKU'
            - type: 'null'
      additionalProperties: false
      allOf:
        - required:
            - type
        - if:
            properties:
              type:
                const: PRODUCT
          then:
            required:
              - product
            properties:
              product:
                $ref: '#/components/schemas/LoyaltyV2ActivityBenefitMaterialProduct'
              sku:
                type: 'null'
        - if:
            properties:
              type:
                const: SKU
          then:
            required:
              - sku
            properties:
              sku:
                $ref: '#/components/schemas/LoyaltyV2ActivityBenefitMaterialSKU'
              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`. 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.
      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`. When `type` is `DISCOUNT_COUPONS`, requests may
            omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: '#/components/schemas/LoyaltyV2ActivityBenefitDigitalGiftVouchers'
            - type: 'null'
        discount_coupons:
          description: >-
            Discount coupons configuration. Required when `type` is
            `DISCOUNT_COUPONS`. When `type` is `GIFT_VOUCHERS`, requests may
            omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitDigitalDiscountCoupons
            - type: 'null'
      additionalProperties: false
      allOf:
        - required:
            - type
        - if:
            properties:
              type:
                const: DISCOUNT_COUPONS
          then:
            required:
              - discount_coupons
            properties:
              discount_coupons:
                $ref: >-
                  #/components/schemas/LoyaltyV2ActivityBenefitDigitalDiscountCoupons
              gift_vouchers:
                type: 'null'
        - if:
            properties:
              type:
                const: GIFT_VOUCHERS
          then:
            required:
              - gift_vouchers
            properties:
              gift_vouchers:
                $ref: >-
                  #/components/schemas/LoyaltyV2ActivityBenefitDigitalGiftVouchers
              discount_coupons:
                type: 'null'
    LoyaltyV2ActivityBenefitStockLimited:
      type: object
      title: Benefit Stock Limited
      description: Limited stock configuration.
      properties:
        quantity:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Available Remaining stock quantity. For responses, updates with each
            benefit purchase.
      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/LoyaltyV2ActivityBenefitPointsProportionalEvery
        total_amount:
          description: >-
            Points per every specified post-discount order amount (for
            `POST_DISCOUNT_ORDER_AMOUNT`).
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalEvery
        metadata:
          description: >-
            Points per every specified value of an order metadata property (for
            `ORDER_METADATA_VALUE`).
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalMetadata
      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/LoyaltyV2ActivityBenefitPointsProportionalMetadata
      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/LoyaltyV2ActivityBenefitPointsProportionalMetadata
      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
    LoyaltyV2ActivityBenefitMaterialProduct:
      type: object
      title: Benefit Material Product
      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
    LoyaltyV2ActivityBenefitMaterialSKU:
      type: object
      title: Benefit Material SKU
      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
    LoyaltyV2ActivityBenefitDigitalGiftVouchers:
      type: object
      title: Benefit Digital Gift Vouchers
      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
    LoyaltyV2ActivityBenefitDigitalDiscountCoupons:
      type: object
      title: Benefit Digital Discount Coupons
      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
    LoyaltyV2ActivityBenefitPointsProportionalEvery:
      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
    LoyaltyV2ActivityBenefitPointsProportionalMetadata:
      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`. In requests, the
        other two may be omitted or set to `null`. In responses, they are
        omitted.
      properties:
        type:
          type: string
          enum:
            - product
            - sku
            - products_collection
          description: Type of the referenced object.
        product:
          description: >-
            Product reference. Required when `type` is `product`. For other
            types, requests may omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct
            - type: 'null'
        sku:
          description: >-
            SKU reference. Required when `type` is `sku`. For other types,
            requests may omit it or set it to `null`; responses omit it.
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku
            - type: 'null'
        products_collection:
          description: >-
            Products collection reference. Required when `type` is
            `products_collection`. For other types, requests may omit it or set
            it to `null`; responses omit it.
          oneOf:
            - $ref: >-
                #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection
            - type: 'null'
      required:
        - type
      additionalProperties: false
      allOf:
        - if:
            properties:
              type:
                const: product
          then:
            required:
              - product
            properties:
              product:
                $ref: >-
                  #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct
              sku:
                type: 'null'
              products_collection:
                type: 'null'
        - if:
            properties:
              type:
                const: sku
          then:
            required:
              - sku
            properties:
              sku:
                $ref: >-
                  #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku
              product:
                type: 'null'
              products_collection:
                type: 'null'
        - if:
            properties:
              type:
                const: products_collection
          then:
            required:
              - products_collection
            properties:
              products_collection:
                $ref: >-
                  #/components/schemas/LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection
              product:
                type: 'null'
              sku:
                type: 'null'
    LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct:
      type: object
      title: Benefit Point Proportional Applicable To Product
      description: Product reference.
      properties:
        id:
          type: string
          pattern: ^prod_[a-f0-9]+
          description: Product ID, prefixed with `prod_`.
      required:
        - id
      additionalProperties: false
    LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku:
      type: object
      title: Benefit Point Proportional Applicable To SKU
      description: SKU reference.
      properties:
        id:
          type: string
          pattern: ^sku_[a-f0-9]+
          description: SKU ID, prefixed with `sku_`.
      required:
        - id
      additionalProperties: false
    LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection:
      type: object
      title: Benefit Point Proportional Products Collection
      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:
    X-App-Id:
      type: apiKey
      name: X-App-Id
      in: header
    X-App-Token:
      type: apiKey
      name: X-App-Token
      in: header
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.