Get Wallet

Retrieve details of a specific wallet by its ID.

GET /v1/wallets/{id}

cURL

curl -X GET "https://api.flexprice.io/v1/wallets/wallet_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "id": "wallet_abc123",
  "customer_id": "cust_1234",
  "name": "Prepaid Wallet - USD",
  "currency": "usd",
  "wallet_type": "PREPAID",
  "wallet_status": "ACTIVE",
  "balance": "75.500000000",
  "credit_balance": "75.500000000",
  "conversion_rate": "1.00000",
  "topup_conversion_rate": "1.00000",
  "description": "Primary wallet for API usage",
  "metadata": {
    "customer_segment": "enterprise"
  },
  "config": {
    "allowed_price_types": ["USAGE"]
  },
  "alert_settings": {
    "alert_enabled": true,
    "threshold_type": "PERCENTAGE",
    "threshold_value": "20.0"
  },
  "alert_state": "OK",
  "auto_topup": {
    "enabled": false
  },
  "credits_available_breakdown": {
    "total": "75.500000000",
    "by_priority": [
      {
        "priority": 1,
        "credits": "50.000000000"
      },
      {
        "priority": null,
        "credits": "25.500000000"
      }
    ],
    "by_expiry": [
      {
        "expiry_date": "2024-12-31T23:59:59Z",
        "credits": "25.500000000"
      },
      {
        "expiry_date": null,
        "credits": "50.000000000"
      }
    ]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

Path Parameters

id · string · required

The unique identifier of the wallet to retrieve

Response

id · string

Unique identifier for the wallet

customer_id · string

ID of the customer this wallet belongs to

name · string

Wallet name

currency · string

Three-letter ISO currency code (e.g., USD, EUR)

wallet_type · string

Type of wallet

Values: PREPAID, POSTPAID

wallet_status · string

Current status of the wallet

Values: ACTIVE, INACTIVE, SUSPENDED

balance · string

Current balance in currency

credit_balance · string

Current balance in credits

conversion_rate · string

Conversion rate from credits to currency during consumption

Example: If conversion_rate is “2”, then 1 credit = 0.5 in currency

topup_conversion_rate · string

Conversion rate for top-ups to the currency

Example: If topup_conversion_rate is “2”, then 1 currency unit = 0.5 credits

description · string

Optional description for the wallet

metadata · object

Custom metadata as key-value pairs

config · object

Wallet configuration

Show Config object

allowed_price_types · array

Price types allowed for this wallet (e.g., [“USAGE”] for prepaid, [“ALL”] for postpaid)

alert_settings · object

Alert configuration for low balance notifications

Show Alert settings object

alert_enabled · boolean

Whether alerts are enabled

threshold_type · string

Type of threshold (PERCENTAGE or ABSOLUTE)

threshold_value · string

Threshold value that triggers alerts

alert_state · string

Current alert state

Values: OK, WARNING, CRITICAL

auto_topup · object

Auto top-up configuration

Show Auto top-up object

enabled · boolean

Whether auto top-up is enabled

threshold · string

Balance threshold that triggers auto top-up

amount · string

Amount to add during auto top-up

credits_available_breakdown · object

Breakdown of available credits by expiry date and priority

Show Breakdown object

total · string

Total available credits

by_priority · array

Credits grouped by priority level

by_expiry · array

Credits grouped by expiration date

created_at · string

Timestamp when wallet was created

updated_at · string

Timestamp when wallet was last updated

cURL

curl -X GET "https://api.flexprice.io/v1/wallets/wallet_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "id": "wallet_abc123",
  "customer_id": "cust_1234",
  "name": "Prepaid Wallet - USD",
  "currency": "usd",
  "wallet_type": "PREPAID",
  "wallet_status": "ACTIVE",
  "balance": "75.500000000",
  "credit_balance": "75.500000000",
  "conversion_rate": "1.00000",
  "topup_conversion_rate": "1.00000",
  "description": "Primary wallet for API usage",
  "metadata": {
    "customer_segment": "enterprise"
  },
  "config": {
    "allowed_price_types": ["USAGE"]
  },
  "alert_settings": {
    "alert_enabled": true,
    "threshold_type": "PERCENTAGE",
    "threshold_value": "20.0"
  },
  "alert_state": "OK",
  "auto_topup": {
    "enabled": false
  },
  "credits_available_breakdown": {
    "total": "75.500000000",
    "by_priority": [
      {
        "priority": 1,
        "credits": "50.000000000"
      },
      {
        "priority": null,
        "credits": "25.500000000"
      }
    ],
    "by_expiry": [
      {
        "expiry_date": "2024-12-31T23:59:59Z",
        "credits": "25.500000000"
      },
      {
        "expiry_date": null,
        "credits": "50.000000000"
      }
    ]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

Understanding Wallet Balance

The wallet balance is represented in two ways:

1. balance: Balance in the wallet’s currency (e.g., USD)
2. credit_balance: Balance in credits

These values are related by the conversion_rate:

balance = credit_balance / conversion_rate

Example:

• credit_balance: 100 credits
• conversion_rate: 2
• balance: 100 / 2 = $50 USD

Credits Available Breakdown

The credits_available_breakdown field provides insight into how credits are organized:

By Priority

Credits with lower priority numbers are consumed first. This is useful for:

• Using promotional credits before paid credits
• Implementing credit hierarchies
• Managing multiple credit sources

Priority null indicates no specific priority (consumed after prioritized credits).

By Expiry

Credits grouped by expiration date. Credits expiring soonest are consumed first.

Expiry null indicates credits that never expire.