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

> List the customers a promotional credit has been granted to, including revoked grants

<Note>
  Filter by `status=granted` or `status=revoked` to narrow results, and use `search` to match on customer name or customer key. Results are paginated — check the `meta` object for `total_count` and `total_pages`.
</Note>


## OpenAPI

````yaml GET /api/v1/credit_systems/promotional-credits/{id}/customers
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}/customers:
    get:
      tags:
        - Promotional Credits
      summary: List customers for a promotional credit
      description: >
        Lists the customers a promotional credit has been granted to, including
        those whose grant has been

        revoked. Use this to audit who currently holds a promotional credit and
        to reconcile grants against your

        own records.


        Filter by `status` to return only currently granted (`granted`) or
        revoked (`revoked`) grants, and use

        `search` to match on customer name or customer key. Results are
        paginated.
      operationId: listPromotionalCreditCustomers
      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
        - name: status
          in: query
          required: false
          description: >-
            Filter grants by status. Omit to return both granted and revoked
            grants.
          schema:
            type: string
            enum:
              - granted
              - revoked
          example: granted
        - name: search
          in: query
          required: false
          description: Filter by customer name or customer key
          schema:
            type: string
          example: cust_001
      responses:
        '200':
          description: Customers for the promotional credit
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Promotional credit customers fetched
                  meta:
                    type: object
                    description: Pagination metadata
                    properties:
                      total_count:
                        type: integer
                      total_pages:
                        type: integer
                  data:
                    type: array
                    items: c572bbb8-743b-48ec-a774-225bf247080b
                  errors:
                    type: object
              example:
                statusCode: 200
                message: Promotional credit customers fetched
                meta:
                  total_count: 1
                  total_pages: 1
                data:
                  - id: a1b2c3d4-0000-0000-0000-000000000001
                    customer_id: f4a2f74c-661b-428c-87f8-75cc1aa19c4c
                    customer_key: cust_001
                    customer_name: Acme Inc
                    customer_email: billing@acme.test
                    active: true
                    applied_at: '2026-06-01T10:00:00Z'
                    revoked_at: null
                    created_at: '2026-06-01T10: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/customers?status=granted"
            \
              -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

````