> ## 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 a customer's wallets

> List the credit wallets that belong to a customer, including each wallet's current balance and topup link.



## OpenAPI

````yaml GET /api/v1/credit_systems/v2/wallets
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/v2/wallets:
    get:
      tags:
        - Wallets
      summary: List a customer's wallets
      description: >
        Retrieves the credit wallets that belong to a customer, with each
        wallet's current balance and topup link.


        Each customer can have multiple wallets — one per credit system they're
        attached to. Use this endpoint as the entry point to a customer's credit
        overview, then call `GET
        /api/v1/credit_systems/v2/wallets/{id}/credit-allocations` for the
        per-allocation `available` vs `used` breakdown.


        The `allocations` field on each wallet is intentionally returned as an
        empty array on this endpoint — fetch them via the credit-allocations
        endpoint when you need them.
      operationId: listWallets
      parameters:
        - name: customer_key
          in: query
          required: true
          description: >-
            The unique identifier of the customer on your platform, saved as
            customer_key on Metrifox
          schema:
            type: string
          example: cust-mljp3ra6ffjm
      responses:
        '200':
          description: Wallets fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletListResponse'
              examples:
                wallets_list:
                  summary: Wallets Response
                  value:
                    statusCode: 200
                    message: Wallets fetched successfully
                    meta: {}
                    data:
                      - id: b7bf0d46-9f7d-4d58-9bb4-6bfb2d3e6a5c
                        name: Image Credits
                        credit_key: image_credits
                        credit_system_id: c17f9a7b-1e49-4f80-9b6e-8d85b4a11f8a
                        credit_unit_singular: credit
                        credit_unit_plural: credits
                        balance: 120
                        low_balance_threshold: 20
                        credit_attachment_id: fb4e18f0-8b9c-4977-9fdd-7a4b76b2e8d3
                        customer_key: cust-mljp3ra6ffjm
                        allocations: []
                        topup_link: >-
                          https://app.metrifox.com/metrifox-inc/wallets/b7bf0d46-9f7d-4d58-9bb4-6bfb2d3e6a5c?customer=cust-mljp3ra6ffjm
                    errors: {}
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: |
            from metrifox_sdk import MetrifoxClient

            client = MetrifoxClient(api_key="your_api_key")

            # List all wallets for a customer
            wallets = client.wallets.list("cust-mljp3ra6ffjm")
            for wallet in wallets['data']:
                print(f"{wallet['name']}: {wallet['balance']} {wallet['credit_unit_plural']}")
        - lang: javascript
          label: Javascript SDK
          source: >
            import { init } from "metrifox-js";


            const metrifoxClient = init({
              apiKey: process.env.METRIFOX_API_KEY
            });


            const wallets = await
            metrifoxClient.wallets.list("cust-mljp3ra6ffjm");

            wallets.data.forEach((w) => {
              console.log(`${w.name}: ${w.balance} ${w.credit_unit_plural}`);
            });
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

            METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" })

            # List all wallets for a customer
            response = METRIFOX_SDK.wallets.list("cust-mljp3ra6ffjm")
            response["data"].each do |wallet|
              puts "#{wallet['name']}: #{wallet['balance']} #{wallet['credit_unit_plural']}"
            end
components:
  schemas:
    WalletListResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Wallets fetched successfully
        meta:
          type: object
          additionalProperties: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/WalletEntity'
        errors:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
    WalletEntity:
      type: object
      properties:
        id:
          type: string
          description: Unique wallet identifier
        name:
          type: string
          description: Name of the wallet (inherited from the credit system)
        credit_key:
          type: string
          description: Unique key for the credit system this wallet belongs to
        credit_system_id:
          type: string
          description: ID of the credit system this wallet belongs to
        credit_unit_singular:
          type: string
          description: Singular form of the credit unit name
        credit_unit_plural:
          type: string
          description: Plural form of the credit unit name
        balance:
          type: number
          description: Current available balance in the wallet
        low_balance_threshold:
          type: number
          nullable: true
          description: >-
            Threshold below which a low-balance signal is emitted (or null if
            unset)
        credit_attachment_id:
          type: string
          nullable: true
          description: ID of the credit attachment currently provisioning into this wallet
        customer_key:
          type: string
          nullable: true
          description: Customer key this wallet belongs to
        allocations:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            Returned as an empty array on the list endpoint. Use `GET
            /api/v1/credit_systems/v2/wallets/{id}/credit-allocations` to fetch
            allocations for a wallet.
        topup_link:
          type: string
          nullable: true
          description: >-
            Metrifox-hosted URL you can open in the browser to let the customer
            top up this wallet. Requires the tenant to have a checkout_username
            configured.
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````