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

> Retrieve a single promotional credit by id



## OpenAPI

````yaml GET /api/v1/credit_systems/promotional-credits/{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/credit_systems/promotional-credits/{id}:
    get:
      tags:
        - Promotional Credits
      summary: Get a promotional credit
      description: >
        Retrieves a single promotional credit by its `id`, including its credit
        system, quantity, schedule, and

        current lifecycle status.
      operationId: getPromotionalCredit
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the promotional credit
          schema:
            type: string
            format: uuid
          example: 625f5cee-259b-4994-b7eb-416b9e551f2c
      responses:
        '200':
          description: Promotional credit
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Promotional credit fetched
                  meta:
                    type: object
                  data:
                    type: object
                    description: >-
                      A promotional credit — a time-bound credit allocation
                      campaign tied to a credit system that can be granted to
                      customers as a consumable balance.
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: >-
                          The unique identifier of the promotional credit. Use
                          this when granting or revoking.
                      name:
                        type: string
                        description: The name of the promotional credit
                      description:
                        type: string
                        nullable: true
                        description: An optional description
                      credit_system_id:
                        type: string
                        format: uuid
                        description: >-
                          The identifier of the credit system this promotional
                          credit funds
                      credit_system_name:
                        type: string
                        description: >-
                          The name of the credit system this promotional credit
                          funds
                      quantity:
                        type: integer
                        description: >-
                          The number of credits granted per reset cycle. Use
                          `-1` for unlimited.
                      reset_interval:
                        type: string
                        description: >-
                          How often the granted quantity renews (e.g. `daily`,
                          `weekly`, `monthly`, or `none`).
                      reset_anchor:
                        type: string
                        nullable: true
                        description: >-
                          The anchor used to align credit resets, when
                          applicable
                      starts_at:
                        type: string
                        format: date-time
                        description: >-
                          When the promotional credit becomes active and can be
                          granted
                      expires_at:
                        type: string
                        format: date-time
                        nullable: true
                        description: When the promotional credit expires, if applicable
                      duration_value:
                        type: integer
                        nullable: true
                        description: >-
                          The numeric part of the access period — how long the
                          granted credit stays valid per customer (paired with
                          `duration_unit`)
                      duration_unit:
                        type: string
                        nullable: true
                        description: >-
                          The unit of the access period (e.g. `day`, `week`,
                          `month`)
                      allow_multiple_grants:
                        type: boolean
                        description: >-
                          Whether this promotional credit can be granted
                          multiple times to the same customer and coexist with
                          other grants
                      status:
                        type: string
                        enum:
                          - scheduled
                          - active
                          - expired
                          - deactivated
                        description: The current lifecycle status of the promotional credit
                      is_applied:
                        type: boolean
                        description: >-
                          Whether the promotional credit is currently applied to
                          at least one customer
                      created_at:
                        type: string
                        format: date-time
                      updated_at:
                        type: string
                        format: date-time
                  errors:
                    type: object
              example:
                statusCode: 200
                message: Promotional credit fetched
                meta: {}
                data:
                  id: 625f5cee-259b-4994-b7eb-416b9e551f2c
                  name: December Campaign Credit
                  description: Bonus credits for the december promotion
                  credit_system_id: 9c1f1d2e-0000-0000-0000-000000000010
                  credit_system_name: Token Credits
                  quantity: 500
                  reset_interval: monthly
                  reset_anchor: null
                  starts_at: '2026-06-01T00:00:00Z'
                  expires_at: '2026-09-01T00:00:00Z'
                  duration_value: 3
                  duration_unit: month
                  allow_multiple_grants: false
                  status: active
                  is_applied: true
                  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 credit 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/credit_systems/promotional-credits/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

````