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

# Get promotional entitlement

> Retrieve a single promotional entitlement by id



## OpenAPI

````yaml GET /api/v1/product_catalogues/promotional-entitlements/{id}
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/{id}:
    get:
      tags:
        - Promotional Entitlements
      summary: Get a promotional entitlement
      description: >
        Retrieves a single promotional entitlement by its `id`, including its
        mode, allowance, schedule, and

        current lifecycle status.
      operationId: getPromotionalEntitlement
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the promotional entitlement
          schema:
            type: string
            format: uuid
          example: 625f5cee-259b-4994-b7eb-416b9e551f2c
      responses:
        '200':
          description: Promotional entitlement
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Promotional entitlement fetched
                  meta:
                    type: object
                  data:
                    type: object
                    description: >-
                      A promotional entitlement — a standalone grant of feature
                      allowance that can be applied to customers outside of a
                      subscription.
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: >-
                          The unique identifier of the promotional entitlement.
                          Use this when granting or revoking.
                      name:
                        type: string
                        description: The name of the promotional entitlement
                      description:
                        type: string
                        nullable: true
                        description: An optional description
                      mode:
                        type: string
                        enum:
                          - additive
                          - override
                        description: >
                          How the grant interacts with the customer's plan
                          allowance.

                          `additive` adds on top of the plan allowance;
                          `override` replaces it.
                      included_allowance:
                        type: integer
                        description: The granted allowance. Use `-1` for unlimited.
                      included_allowance_reset_interval:
                        type: string
                        description: >-
                          How often the allowance resets (e.g. `daily`,
                          `weekly`, `monthly`, or `none`).
                      included_allowance_reset_anchor:
                        type: string
                        nullable: true
                        description: >-
                          The anchor used to align allowance resets, when
                          applicable
                      starts_at:
                        type: string
                        format: date-time
                        description: When the promotional entitlement becomes active
                      expires_at:
                        type: string
                        format: date-time
                        nullable: true
                        description: >-
                          When the promotional entitlement expires, if
                          applicable
                      duration_value:
                        type: integer
                        nullable: true
                        description: >-
                          The numeric part of the grant duration (paired with
                          `duration_unit`)
                      duration_unit:
                        type: string
                        nullable: true
                        description: >-
                          The unit of the grant duration (e.g. `day`, `week`,
                          `month`)
                      status:
                        type: string
                        enum:
                          - scheduled
                          - active
                          - expired
                          - deactivated
                        description: >-
                          The current lifecycle status of the promotional
                          entitlement
                      is_applied:
                        type: boolean
                        description: >-
                          Whether the promotional entitlement is currently
                          applied to at least one customer
                      feature_id:
                        type: string
                        format: uuid
                        description: >-
                          The identifier of the feature this promotional
                          entitlement grants
                      feature_name:
                        type: string
                        description: The name of the granted feature
                      feature_type:
                        type: string
                        description: The type of the granted feature
                      created_at:
                        type: string
                        format: date-time
                      updated_at:
                        type: string
                        format: date-time
                  errors:
                    type: object
              example:
                statusCode: 200
                message: Promotional entitlement fetched
                meta: {}
                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'
        '404':
          description: Promotional entitlement not found
          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/625f5cee-259b-4994-b7eb-416b9e551f2c
            \
              -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

````