Auto Top-Up - FlexPrice

Overview

Auto top-up automatically adds credits to a customer’s wallet when the balance falls below a specified threshold. This ensures uninterrupted service and provides a seamless credit management experience.

How Auto Top-Up Works

Balance monitoring

FlexPrice monitors wallet balances after each transaction (credit or debit).

Threshold check

When balance falls below the configured threshold, auto top-up is triggered.

Credit addition

The configured amount of credits is added to the wallet.

Invoice generation (optional)

If invoicing is enabled, an invoice is created for the credit purchase.

Configuration

Auto top-up is configured at the wallet level using the auto_topup object:

{
  "auto_topup": {
    "enabled": true,
    "threshold": "50.00",
    "amount": "200.00",
    "invoicing": true
  }
}

Configuration Fields

Field	Type	Required	Description
`enabled`	boolean	Yes	Whether auto top-up is active
`threshold`	decimal	Yes	Balance level that triggers top-up (in credits)
`amount`	decimal	Yes	Credits to add when triggered (in credits)
`invoicing`	boolean	Yes	Whether to create an invoice for the top-up

All amounts are in credit units, not currency units. Use the wallet’s conversion_rate to convert between credits and currency.

Setting Up Auto Top-Up

On Wallet Creation

Include auto top-up settings when creating a new wallet:

POST /v1/wallets
{
  "customer_id": "cust_1234567890",
  "currency": "usd",
  "wallet_type": "PRE_PAID",
  "conversion_rate": "1.0",
  "initial_credits_to_load": "500.00",
  "auto_topup": {
    "enabled": true,
    "threshold": "100.00",
    "amount": "250.00",
    "invoicing": true
  }
}

On Existing Wallet

Update an existing wallet to enable auto top-up:

PATCH /v1/wallets/{wallet_id}
{
  "auto_topup": {
    "enabled": true,
    "threshold": "50.00",
    "amount": "200.00",
    "invoicing": false
  }
}

Disable Auto Top-Up

Set enabled to false to disable without removing configuration:

PATCH /v1/wallets/{wallet_id}
{
  "auto_topup": {
    "enabled": false
  }
}

Top-Up Behavior

Trigger Conditions

Auto top-up is evaluated:

After credit transactions - When credits are added to the wallet
After debit transactions - When credits are consumed
After wallet balance calculations - Real-time balance updates

Auto top-up evaluates the credit_balance, not the currency balance. Ensure your threshold and amount are set appropriately.

Threshold Evaluation

Top-up triggers when: credit_balance < threshold Example:

{
  "threshold": "50.00",
  "amount": "200.00"
}

Current Balance	Action
75.00	No action (above threshold)
50.00	No action (equal to threshold)
49.99	Top up 200.00 credits
10.00	Top up 200.00 credits

The top-up amount is fixed - it doesn’t calculate to reach a target balance. If balance is 10 and amount is 200, the new balance will be 210.

Transaction Reason

Auto top-up transactions are recorded with: With invoicing:

{
  "transaction_reason": "PURCHASED_CREDIT_INVOICED"
}

Without invoicing:

{
  "transaction_reason": "PURCHASED_CREDIT_DIRECT"
}

Invoicing Behavior

When `invoicing: true`

Credits added to wallet

The configured amount is immediately added to wallet as pending credits.

Invoice created

An invoice is generated for the credit purchase:

{
  "customer_id": "cust_1234567890",
  "line_items": [
    {
      "description": "Credit purchase (auto top-up)",
      "quantity": 200.00,
      "unit_price": 1.00,
      "amount": 200.00
    }
  ],
  "total": 200.00,
  "status": "open"
}

Payment required

Customer must pay the invoice to finalize credits. Until paid:

Credits show as PENDING in transaction
Credits cannot be used for consumption
Invoice appears in customer’s unpaid balance

Credits activated on payment

Once invoice is paid:

Transaction status changes to COMPLETED
Credits become available for use
Wallet balance is updated

When `invoicing: false`

Credits immediately added

Credits are added directly to the wallet with COMPLETED status.

No invoice created

No invoice is generated - this is a free top-up.

Credits immediately available

Customer can use credits right away.

Use invoicing: false for promotional credits or when billing is handled externally. Use invoicing: true when customers should be charged for the top-up.

Use Cases

Prepaid Service Plans

{
  "auto_topup": {
    "enabled": true,
    "threshold": "100.00",
    "amount": "500.00",
    "invoicing": true
  }
}

Customer gets charged automatically when balance is low, ensuring uninterrupted service.

Promotional Credit Maintenance

{
  "auto_topup": {
    "enabled": true,
    "threshold": "10.00",
    "amount": "50.00",
    "invoicing": false
  }
}

Automatically provide promotional credits to keep free-tier users engaged.

Enterprise Credit Buffer

{
  "auto_topup": {
    "enabled": true,
    "threshold": "1000.00",
    "amount": "5000.00",
    "invoicing": true
  }
}

Maintain a healthy credit buffer for high-volume enterprise customers.

Development/Testing Credits

{
  "auto_topup": {
    "enabled": true,
    "threshold": "5.00",
    "amount": "25.00",
    "invoicing": false
  }
}

Keep development accounts topped up without billing.

Monitoring Auto Top-Up

Check Auto Top-Up Status

Retrieve wallet with auto top-up configuration:

GET /v1/wallets/{wallet_id}

Response includes:

{
  "id": "wallet_1234567890",
  "credit_balance": "75.00",
  "auto_topup": {
    "enabled": true,
    "threshold": "50.00",
    "amount": "200.00",
    "invoicing": true
  }
}

Track Top-Up Transactions

Filter wallet transactions to see auto top-ups:

GET /v1/wallets/{wallet_id}/transactions
  ?transaction_reason=PURCHASED_CREDIT_INVOICED
  &type=CREDIT

Monitor Top-Up Invoices

Find invoices created by auto top-up:

GET /v1/invoices
  ?customer_id=cust_1234567890
  &metadata.source=auto_topup

Best Practices

Threshold Sizing

Calculate average consumption

Determine typical daily or weekly credit usage:

Low usage: 10-50 credits/day
Medium usage: 50-500 credits/day
High usage: 500+ credits/day

Set threshold for buffer

Configure threshold to provide 3-7 days of buffer:

Low: threshold = 100-200 credits
Medium: threshold = 500-1000 credits
High: threshold = 2000-5000 credits

Size top-up amount

Set amount to 2-4x the threshold:

If threshold = 100, amount = 200-400
If threshold = 1000, amount = 2000-4000

Prevent Over-Billing

Set reasonable amount values to avoid large unexpected charges
Use threshold high enough to prevent frequent top-ups
Monitor customers with frequent auto top-ups (may indicate usage spikes)
Consider usage alerts in addition to auto top-up

Test Configuration

Create a test wallet with auto top-up
Manually debit credits to trigger threshold
Verify credits are added
If invoicing is enabled, check invoice creation
Confirm transaction appears in wallet history
Test disabling and re-enabling

Communication

Notify customers when auto top-up is enabled on their account
Send emails when auto top-up is triggered
Include top-up transactions in billing summaries
Allow customers to configure their own thresholds (via self-service portal)

Conversion Rate Considerations

Auto top-up uses the wallet’s topup_conversion_rate for invoicing:

{
  "conversion_rate": "1.0",
  "topup_conversion_rate": "1.0",
  "auto_topup": {
    "threshold": "50.00",
    "amount": "200.00",
    "invoicing": true
  }
}

Invoice calculation:

credits = 200.00
topup_conversion_rate = 1.0
invoice_amount = credits × topup_conversion_rate = 200.00 USD

If topup_conversion_rate differs from conversion_rate, customers may pay a different rate for auto top-up credits versus credit consumption.

Limitations

Cannot Customize Per Top-Up

Amount is fixed in configuration
Cannot vary based on balance or usage patterns
No dynamic pricing or volume discounts

Workaround: Use webhooks to detect low balance and trigger custom top-up logic via API.

Single Threshold

Only one threshold can be configured
Cannot set multiple tiers (e.g., 50 credits at threshold 100, 200 credits at threshold 20)

Workaround: Implement custom logic using balance alerts and API-driven top-ups.

No Scheduling

Triggers based on balance only
Cannot schedule regular top-ups (e.g., “every Monday”)

Workaround: Use recurring credit grants at the plan level for scheduled credit allocation.

Security Considerations

Invoicing Enabled

Customer must have valid payment method on file
Failed payments will leave credits in PENDING state
Consider payment retry policies
Set invoice due dates appropriately

Invoicing Disabled

No payment validation occurs
Credits are granted immediately
Monitor for abuse if exposed to self-service
Consider rate limiting or maximum top-up amounts

Wallet Permissions

Restrict who can enable/disable auto top-up
Log configuration changes for audit
Validate threshold and amount ranges (prevent $10,000 auto top-ups by accident)

Troubleshooting

Top-Up Not Triggering

Check balance calculation:

GET /v1/wallets/{wallet_id}/balance?include_real_time_balance=true

Ensure credit_balance is actually below threshold. Verify configuration:

GET /v1/wallets/{wallet_id}

Confirm auto_topup.enabled = true and values are correct. Check recent transactions: May have recently triggered - check for transactions with reason PURCHASED_CREDIT_INVOICED.

Credits Added But Not Available

If invoicing: true, credits remain PENDING until invoice is paid:

GET /v1/invoices?customer_id=cust_1234567890&status=open

Pay or void the invoice to complete or cancel the top-up.

Multiple Top-Ups in Short Period

If balance drops below threshold multiple times quickly:

Increase amount to provide larger buffer
Increase threshold to trigger earlier
Investigate usage spike causing rapid consumption

Next Steps

Wallets

Learn about wallet configuration

Credit Grants

Set up automatic credit allocation

Alerts

Configure balance notifications

Invoices

Understand invoice creation

Get Started

Core Concepts

Usage Metering

Pricing & Plans

Credits & Wallets

Billing & Invoicing

Integrations

Self-Hosting

​Overview

​How Auto Top-Up Works

​Configuration

​Configuration Fields

​Setting Up Auto Top-Up

​On Wallet Creation

​On Existing Wallet

​Disable Auto Top-Up

​Top-Up Behavior

​Trigger Conditions

​Threshold Evaluation

​Transaction Reason

​Invoicing Behavior

​When invoicing: true

​When invoicing: false

​Use Cases

​Prepaid Service Plans

​Promotional Credit Maintenance

​Enterprise Credit Buffer

​Development/Testing Credits

​Monitoring Auto Top-Up

​Check Auto Top-Up Status

​Track Top-Up Transactions

​Monitor Top-Up Invoices

​Best Practices

​Threshold Sizing

​Prevent Over-Billing

​Test Configuration

​Communication

​Conversion Rate Considerations

​Limitations

​Cannot Customize Per Top-Up

​Single Threshold

​No Scheduling

​Security Considerations

​Invoicing Enabled

​Invoicing Disabled

​Wallet Permissions

​Troubleshooting

​Top-Up Not Triggering

​Credits Added But Not Available

​Multiple Top-Ups in Short Period

​Next Steps

Wallets

Credit Grants

Alerts

Invoices

Overview

How Auto Top-Up Works

Configuration

Configuration Fields

Setting Up Auto Top-Up

On Wallet Creation

On Existing Wallet

Disable Auto Top-Up

Top-Up Behavior

Trigger Conditions

Threshold Evaluation

Transaction Reason

Invoicing Behavior

When `invoicing: true`

When `invoicing: false`

Use Cases

Prepaid Service Plans

Promotional Credit Maintenance

Enterprise Credit Buffer

Development/Testing Credits

Monitoring Auto Top-Up

Check Auto Top-Up Status

Track Top-Up Transactions

Monitor Top-Up Invoices

Best Practices

Threshold Sizing

Prevent Over-Billing

Test Configuration

Communication

Conversion Rate Considerations

Limitations

Cannot Customize Per Top-Up

Single Threshold

No Scheduling

Security Considerations

Invoicing Enabled

Invoicing Disabled

Wallet Permissions

Troubleshooting

Top-Up Not Triggering

Credits Added But Not Available

Multiple Top-Ups in Short Period

Next Steps