> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List promotional entitlements

> List promotional entitlements to discover the id to grant to customers

<Note>
  Use this to find the `id` of the promotional entitlement you want to grant. Pass that `id` to the [Grant promotional entitlement](/api-reference/promotional-entitlements/grant) endpoint.
</Note>

<Note>
  Filter by `status` (`scheduled`, `active`, `expired`, `deactivated`), by `feature_id`, or by `search` (matches the name). Results are paginated — see the `meta` object.
</Note>


## OpenAPI

````yaml GET /api/v1/product_catalogues/promotional-entitlements
openapi: 3.0.1
info:
  title: Metrifox API Documentation
  version: v1
  description: >-
    Welcome to Metrifox Platform's API documentation. This comprehensive API
    suite enables seamless integration with our platform, providing secure and
    efficient access to our services.
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: api.metrifox.com
security:
  - api_key: []
paths:
  /api/v1/product_catalogues/promotional-entitlements:
    get:
      tags:
        - Promotional Entitlements
      summary: List promotional entitlements
      description: >
        Lists the promotional entitlements configured in your account. Use this
        to discover the `id` of the

        promotional entitlement you want to grant (apply) to customers.


        Filter by `feature_id`, `status`, or `search` (matches on name). Results
        are paginated — check the `meta`

        object for pagination details.
      operationId: listPromotionalEntitlements
      parameters:
        - name: feature_id
          in: query
          required: false
          description: Filter by the feature the promotional entitlement grants
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          required: false
          description: Filter by lifecycle status
          schema:
            type: string
            enum:
              - scheduled
              - active
              - expired
              - deactivated
          example: active
        - name: search
          in: query
          required: false
          description: Filter by promotional entitlement name
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: The page of results to return
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: Number of records per page
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Promotional entitlements
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Promotional entitlements fetched
                  meta:
                    type: object
                    description: Pagination metadata
                    properties:
                      current_page:
                        type: integer
                      total_pages:
                        type: integer
                      total_count:
                        type: integer
                      next_page:
                        type: integer
                        nullable: true
                      prev_page:
                        type: integer
                        nullable: true
                  data:
                    type: array
                    items: ed427fe6-c814-47b3-ae49-2a3d154a7f8f
                  errors:
                    type: object
              example:
                statusCode: 200
                message: Promotional entitlements fetched
                meta:
                  current_page: 1
                  total_pages: 1
                  total_count: 1
                  next_page: null
                  prev_page: null
                data:
                  - id: 625f5cee-259b-4994-b7eb-416b9e551f2c
                    name: Summer Campaign Boost
                    description: Extra API calls for the summer promotion
                    mode: additive
                    included_allowance: 1000
                    included_allowance_reset_interval: monthly
                    included_allowance_reset_anchor: null
                    starts_at: '2026-06-01T00:00:00Z'
                    expires_at: '2026-09-01T00:00:00Z'
                    duration_value: 3
                    duration_unit: month
                    status: active
                    is_applied: true
                    feature_id: 9c1f1d2e-0000-0000-0000-000000000010
                    feature_name: API Calls
                    feature_type: metered
                    created_at: '2026-05-20T10:00:00Z'
                    updated_at: '2026-05-20T10:00:00Z'
                errors: {}
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >
            curl -X GET
            "https://api.metrifox.com/api/v1/product_catalogues/promotional-entitlements?status=active"
            \
              -H "x-api-key: your_api_key"
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````