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

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

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

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


## OpenAPI

````yaml GET /api/v1/credit_systems/promotional-credits
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:
    get:
      tags:
        - Promotional Credits
      summary: List promotional credits
      description: >
        Lists the promotional credits configured in your account. Use this to
        discover the `id` of the

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


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

        `meta` object for pagination details.
      operationId: listPromotionalCredits
      parameters:
        - name: credit_system_id
          in: query
          required: false
          description: Filter by the credit system the promotional credit funds
          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 credit 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 credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Promotional credits 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: 97249f45-6260-4439-9e72-0f2424b9a550
                  errors:
                    type: object
              example:
                statusCode: 200
                message: Promotional credits 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: 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'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >
            curl -X GET
            "https://api.metrifox.com/api/v1/credit_systems/promotional-credits?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

````