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

> ⚠️ **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.

Returns a cursor-paginated list of loyalty programs. Supports filtering by `id`, `name`,
`status` and `created_at`. The same field cannot be used in both ascending and descending
order at once.




## OpenAPI

````yaml /openapi/loyalties-v2.json get /v2/loyalties/programs
openapi: 3.1.0
info:
  title: Voucherify Loyalty v2 API
  version: 2.0.0
  description: >-
    Complete OpenAPI specification for the Voucherify Loyalty v2 API.

    All endpoints require the LOYALTY_V2 feature flag.


    Combined from per-domain specs: programs.yaml, members.yaml,
    program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
    tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
  - url: '{protocol}://{host}'
    variables:
      protocol:
        default: https
        enum:
          - https
          - http
      host:
        default: api.voucherify.io
security:
  - bearerAuth: []
    X-App-Id: []
    X-App-Token: []
tags:
  - name: Programs
    description: >-
      Loyalty program CRUD, lifecycle management, program-scoped resource
      assignments (card definitions, earning rules, rewards, tier structures),
      member management (create, list, get, activate, deactivate, delete), card
      operations (points adjustment, pending points, expiring points,
      transactions), reward purchases, and activity history.
  - name: Card Definitions
    description: >-
      CRUD operations, lifecycle management, and activity history for card
      definitions. Card definitions describe the configuration for loyalty
      cards, including code generation, points expiration, earning/spending
      limits, pending points, refunds, and balance settings.
  - name: Earning Rules
    description: >-
      Manage earning rules that define how customers earn points or receive
      incentives based on triggers (events, segments, custom events). Includes
      CRUD, lifecycle, and activity history.
  - name: Tier Structures
    description: >-
      CRUD operations, lifecycle management, and activity history for tier
      structures. Includes nested tier definitions (create, list, update,
      delete) within tier structures. Tier structures define the tiering model
      for loyalty programs — how members qualify for and move between tiers.
  - name: Benefits
    description: >-
      Manage benefit definitions (fixed points, proportional points, material,
      digital). Includes CRUD, lifecycle transitions, and activity history.
  - name: Rewards
    description: >-
      CRUD, lifecycle operations, and activity history for reward definitions.
      Rewards can be material (product/SKU) or digital (discount coupons, gift
      vouchers).
  - name: Examine
    description: >-
      Evaluation endpoints that estimate earning opportunities and reward
      availability for a customer across their loyalty program memberships,
      without side effects.
paths:
  /v2/loyalties/programs:
    get:
      tags:
        - Programs
      summary: List programs
      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.


        Returns a cursor-paginated list of loyalty programs. Supports filtering
        by `id`, `name`,

        `status` and `created_at`. The same field cannot be used in both
        ascending and descending

        order at once.
      operationId: listPrograms
      parameters:
        - name: filters
          in: query
          required: false
          description: >
            Filters for the program list. Nested object serialized in the query
            string

            (e.g. `filters[status][conditions][$is]=ACTIVE`). Each field accepts
            a `conditions`

            object with at least one condition. Only the condition operators
            supported by each

            field type are allowed.
          style: deepObject
          explode: true
          schema:
            oneOf:
              - $ref: '#/components/schemas/ProgramListFilters'
              - type: 'null'
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of items to return. Between 1 and 100. Defaults to
            10. Non-integer values are rounded.
          schema:
            type:
              - number
              - string
              - 'null'
            minimum: 1
            maximum: 100
            default: 10
        - name: order
          in: query
          required: false
          description: >
            Sorting order. A single value or an array of values. Prefix a field
            with `-` for

            descending order. Defaults to `-created_at`. The same field cannot
            be used in both

            ascending and descending order at once.
          schema:
            oneOf:
              - type: array
                items:
                  type: string
                  enum:
                    - '-created_at'
                    - created_at
                    - name
                    - '-name'
              - type: string
                enum:
                  - '-created_at'
                  - created_at
                  - name
                  - '-name'
              - type: 'null'
        - name: cursor
          in: query
          required: false
          description: Pagination cursor returned by a previous call (`cursor.next`).
          schema:
            type:
              - string
              - 'null'
            pattern: ^lcrsprg_[a-f0-9]+$
      responses:
        '200':
          description: Paginated list of programs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramListResponse'
        '400':
          description: >-
            Validation error - request body or query parameters failed
            validation, or the operation is not allowed in the current resource
            state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - e.g. duplicate resource or invalid state transition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ProgramListFilters:
      type: object
      description: Filters accepted by the program list endpoint.
      properties:
        junction:
          description: Logical junction applied between field filters. Defaults to `AND`.
          oneOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
        id:
          description: Filter by program id.
          oneOf:
            - $ref: '#/components/schemas/ProgramIdFilterConditions'
            - type: 'null'
        name:
          description: Filter by program name.
          oneOf:
            - $ref: '#/components/schemas/ProgramStringFilterConditions'
            - type: 'null'
        status:
          description: Filter by program status.
          oneOf:
            - $ref: '#/components/schemas/ProgramStatusFilterConditions'
            - type: 'null'
        created_at:
          description: Filter by program creation date.
          oneOf:
            - $ref: '#/components/schemas/ProgramDateFilterConditions'
            - type: 'null'
      additionalProperties: false
    ProgramListResponse:
      type: object
      description: Cursor-paginated list of programs.
      properties:
        object:
          type: string
          description: Object type marker.
          const: list
        data:
          type: array
          description: Programs on the current page.
          items:
            $ref: '#/components/schemas/Program'
        cursor:
          description: Pagination cursor, or null when there are no more results.
          oneOf:
            - $ref: '#/components/schemas/ProgramListCursor'
            - type: 'null'
    ErrorResponse:
      type: object
      description: Standard error response returned by all Loyalty v2 endpoints.
      properties:
        code:
          type: integer
          description: HTTP status code of the error.
        key:
          type: string
          description: Machine-readable error key.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Additional details about the error.
        request_id:
          type: string
          description: Identifier of the request that produced the error.
    ProgramIdFilterConditions:
      type: object
      description: >
        Filter conditions for the program `id` field (ID field type). Allowed
        conditions:

        `$is`, `$is_not`, `$in`, `$not_in`. Values must match the program id
        pattern

        `^lprg_[a-f0-9]+$`. Each condition accepts a single string or an array
        of strings

        (max 1 item for `$is`/`$is_not`, max 100 items for `$in`/`$not_in`).
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Field equals the given id.
              oneOf:
                - type: string
                  pattern: ^lprg_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lprg_[a-f0-9]+$
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: Field does not equal the given id.
              oneOf:
                - type: string
                  pattern: ^lprg_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lprg_[a-f0-9]+$
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: Field equals any of the given ids.
              oneOf:
                - type: string
                  pattern: ^lprg_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lprg_[a-f0-9]+$
                  minItems: 1
                  maxItems: 100
                - type: 'null'
            $not_in:
              description: Field equals none of the given ids.
              oneOf:
                - type: string
                  pattern: ^lprg_[a-f0-9]+$
                - type: array
                  items:
                    type: string
                    pattern: ^lprg_[a-f0-9]+$
                  minItems: 1
                  maxItems: 100
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    ProgramStringFilterConditions:
      type: object
      description: >
        Filter conditions for string fields (STRING field type). Allowed
        conditions:

        `$is`, `$is_not`, `$contains`, `$not_contain`, `$starts_with`,
        `$ends_with`,

        `$in`, `$not_in`, `$has_value`, `$is_unknown`. Each condition accepts a
        single

        string or an array of strings (max 1 item, except `$in`/`$not_in` which
        allow

        up to 10 items).
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Field equals the given value.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: Field does not equal the given value.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $contains:
              description: Field contains the given substring.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $not_contain:
              description: Field does not contain the given substring.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $starts_with:
              description: Field starts with the given prefix.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $ends_with:
              description: Field ends with the given suffix.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: Field equals any of the given values (up to 10).
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $not_in:
              description: Field equals none of the given values (up to 10).
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $has_value:
              description: Field has a value (is not null).
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
            $is_unknown:
              description: Field has no value (is null).
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    ProgramStatusFilterConditions:
      type: object
      description: >
        Filter conditions for the program `status` field (ENUM field type).
        Allowed conditions:

        `$is`, `$is_not`, `$in`, `$not_in`. Allowed values: `ACTIVE`,
        `INACTIVE`, `DRAFT`.

        Each condition accepts a single value or an array of values (max 1 item
        for

        `$is`/`$is_not`, up to 10 items for `$in`/`$not_in`).
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $is:
              description: Field equals the given status.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is_not:
              description: Field does not equal the given status.
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $in:
              description: Field equals any of the given statuses (up to 10).
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 10
                - type: 'null'
            $not_in:
              description: Field equals none of the given statuses (up to 10).
              oneOf:
                - type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                    - DRAFT
                - type: array
                  items:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - DRAFT
                  minItems: 1
                  maxItems: 10
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    ProgramDateFilterConditions:
      type: object
      description: >
        Filter conditions for date fields (DATE field type). Allowed conditions:

        `$before`, `$after` (date values), `$is`, `$more_than`, `$less_than`

        (non-negative integers, interpreted as a number of days), `$has_value`,
        `$is_unknown`.

        Each condition accepts a single value or an array with a single value.
      properties:
        conditions:
          type: object
          minProperties: 1
          additionalProperties: false
          properties:
            $before:
              description: Field is before the given date.
              oneOf:
                - type: string
                  format: date-time
                - type: array
                  items:
                    type: string
                    format: date-time
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $after:
              description: Field is after the given date.
              oneOf:
                - type: string
                  format: date-time
                - type: array
                  items:
                    type: string
                    format: date-time
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $is:
              description: >-
                Field is exactly the given number of days ago. A non-negative
                integer number of days.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $more_than:
              description: >-
                Field is more than the given number of days ago. A non-negative
                integer number of days.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $less_than:
              description: >-
                Field is less than the given number of days ago. A non-negative
                integer number of days.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1
                - type: 'null'
            $has_value:
              description: Field has a value (is not null).
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
            $is_unknown:
              description: Field has no value (is null).
              oneOf:
                - type: string
                - type: array
                  maxItems: 1
                - type: 'null'
      required:
        - conditions
      additionalProperties: false
    Program:
      type: object
      description: A loyalty program.
      properties:
        id:
          type: string
          description: Unique program identifier.
          pattern: ^lprg_[a-f0-9]+$
        name:
          type: string
          description: Program name.
        status:
          type: string
          description: Program status.
          enum:
            - DRAFT
            - ACTIVE
            - INACTIVE
            - DELETED
        start_date:
          type:
            - string
            - 'null'
          format: date-time
          description: Program validity start date (ISO 8601), or null when not set.
        end_date:
          type:
            - string
            - 'null'
          format: date-time
          description: Program validity end date (ISO 8601), or null when not set.
        validity_hours:
          $ref: '#/components/schemas/ProgramValidityHours'
          description: Validity hours configuration. Defaults to type `ANY_TIME`.
        metadata:
          type: object
          description: Arbitrary key-value metadata. Defaults to `{}`.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Last update timestamp (ISO 8601), or null when never updated.
        object:
          type: string
          description: Object type marker.
          const: program
    ProgramListCursor:
      type: object
      description: >-
        Cursor for fetching the next page of results. Present only when more
        results are available.
      properties:
        next:
          type: string
          description: >-
            Cursor id to pass as the `cursor` query parameter in the next
            request.
        expires_at:
          type: string
          format: date-time
          description: Timestamp after which the cursor expires and can no longer be used.
    ProgramValidityHours:
      type: object
      description: Validity hours configuration of the program.
      properties:
        type:
          type: string
          description: Validity hours mode.
          enum:
            - DAILY
            - ANY_TIME
        daily:
          type: array
          description: Daily validity windows. Present only when `type` is `DAILY`.
          items:
            $ref: '#/components/schemas/ProgramValidityDailyHours'
    ProgramValidityDailyHours:
      type: object
      description: A single daily validity-hours window.
      properties:
        days_of_week:
          type: array
          description: Days of week the window applies to. 0 = Sunday through 6 = Saturday.
          items:
            type: integer
            minimum: 0
            maximum: 6
        start_time:
          type: string
          description: Window start time in `HH:mm` format.
        end_time:
          type: string
          description: Window end time in `HH:mm` format.
  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

````