Create Wallet

Create a prepaid or postpaid wallet for a customer to manage credits and usage-based billing.

POST /v1/wallets

cURL

curl -X POST "https://api.flexprice.io/v1/wallets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_1234",
    "currency": "usd",
    "wallet_type": "PREPAID",
    "conversion_rate": "1",
    "initial_credits_to_load": "100.00"
  }'

201

{
  "id": "wallet_abc123",
  "customer_id": "cust_1234",
  "name": "Prepaid Wallet - USD",
  "currency": "usd",
  "wallet_type": "PREPAID",
  "wallet_status": "ACTIVE",
  "balance": "100.000000000",
  "credit_balance": "100.000000000",
  "conversion_rate": "1.00000",
  "topup_conversion_rate": "1.00000",
  "alert_state": "OK",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Request Body

customer_id · string

The ID of the customer this wallet belongs to. Either customer_id or external_customer_id is required.

external_customer_id · string

The external customer ID from your system. Either customer_id or external_customer_id is required.

currency · string · required

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

wallet_type · string · default: "PREPAID"

Type of wallet

Values:

• PREPAID: Customer must load credits before usage
• POSTPAID: Customer can use credits and pay later

conversion_rate · string · default: "1"

Conversion rate from wallet credits to currency during consumption

Examples:

• 1: 1 credit = 1 USD
• 2: 1 credit = 0.5 USD (2 credits per dollar)
• 0.5: 1 credit = 2 USD (0.5 credits per dollar)

topup_conversion_rate · string

Conversion rate for top-ups to the currency. If not provided, uses conversion_rate.

Examples:

• 1: 1 USD = 1 credit
• 2: 1 USD = 0.5 credits
• 0.5: 1 USD = 2 credits

initial_credits_to_load · string · default: "0"

Number of credits to load into the wallet upon creation (not currency amount)

initial_credits_expiry_date_utc · string

Expiry date for initial credits in ISO 8601 format (e.g., 2025-12-31T23:59:59Z)

If not set, credits don’t expire.

description · string

Optional description for the wallet

metadata · object

Custom metadata as key-value pairs

alert_settings · object

Alert configuration for low balance notifications

Show Alert settings object

alert_enabled · boolean · default: "false"

Enable or disable alerts

threshold_type · string

Type of threshold

Values: PERCENTAGE, ABSOLUTE

threshold_value · string

Threshold value (percentage or absolute amount)

auto_topup · object

Auto top-up configuration

Show Auto top-up object

enabled · boolean · default: "false"

Enable automatic top-ups when balance is low

threshold · string

Balance threshold that triggers auto top-up

amount · string

Amount to add during auto top-up

price_unit · string

Price unit code to use for wallet creation. If provided, overrides currency and conversion_rate with values from the price unit.

Response

id · string

Unique identifier for the wallet

customer_id · string

ID of the customer this wallet belongs to

name · string

Auto-generated wallet name (e.g., “Prepaid Wallet - USD”)

currency · string

Three-letter ISO currency code

wallet_type · string

Type of wallet (PREPAID or 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

topup_conversion_rate · string

Conversion rate for top-ups

alert_settings · object

Alert configuration

alert_state · string

Current alert state

Values: OK, WARNING, CRITICAL

auto_topup · object

Auto top-up configuration

metadata · object

Custom metadata

created_at · string

Timestamp when wallet was created

updated_at · string

Timestamp when wallet was last updated

cURL

curl -X POST "https://api.flexprice.io/v1/wallets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_1234",
    "currency": "usd",
    "wallet_type": "PREPAID",
    "conversion_rate": "1",
    "initial_credits_to_load": "100.00"
  }'

201

{
  "id": "wallet_abc123",
  "customer_id": "cust_1234",
  "name": "Prepaid Wallet - USD",
  "currency": "usd",
  "wallet_type": "PREPAID",
  "wallet_status": "ACTIVE",
  "balance": "100.000000000",
  "credit_balance": "100.000000000",
  "conversion_rate": "1.00000",
  "topup_conversion_rate": "1.00000",
  "alert_state": "OK",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Wallet Types Explained

Prepaid Wallet

A prepaid wallet requires customers to load credits before using your service.

Use cases:

• Pay-as-you-go models
• Promotional credits
• Preventing overages
• Prepaid customer segments

Behavior:

• Usage is blocked when balance reaches zero
• Credits must be added before additional usage
• Suitable for usage-based pricing only

Postpaid Wallet

A postpaid wallet allows customers to use services and pay later through invoicing.

Use cases:

• Enterprise customers
• Net payment terms
• Monthly invoicing cycles
• Customers with credit arrangements

Behavior:

• Balance can go negative
• Usage tracked and invoiced periodically
• Supports all price types (fixed, usage, tiered, etc.)

Conversion Rate Examples

Conversion rates allow you to decouple internal credit accounting from actual currency values.

Example 1: 1:1 conversion

{
  "conversion_rate": "1",
  "currency": "usd"
}

Result: 1 credit = $1.00 USD

Example 2: Bulk discount pricing

{
  "conversion_rate": "0.8",
  "currency": "usd"
}

Result: 1 credit = $0.80 USD (customer gets 25% more value)

Example 3: Premium pricing

{
  "conversion_rate": "1.5",
  "currency": "usd"
}

Result: 1 credit = $1.50 USD