Waymaker API
WaymakerAPI
Developer Documentation
Documentation

Auto Top-Up Configuration

Last Updated: October 15, 2025 Category: Billing

Overview

Auto top-up automatically purchases credits when your balance drops below a threshold you set. This prevents service interruptions for production applications while giving you control over spending through configurable limits.

How it works:

  1. Set a threshold (e.g., 500 credits remaining)
  2. Set a purchase amount (e.g., buy 1,100 credits for $10)
  3. Optionally set a monthly spending limit
  4. System checks your balance hourly
  5. When balance drops below threshold, credits are purchased automatically
  6. You receive email confirmation of the purchase

💡 Inspired by OpenAI's billing model - A proven approach for API credit management.

Prerequisites

Before enabling auto top-up:

  • ✅ Payment method saved in Stripe
  • ✅ At least one successful manual credit purchase completed
  • ✅ API key created and active

⚠️ Important: You must have a saved payment method before enabling auto top-up. The system cannot prompt for payment during automatic purchases.

Step-by-Step: Enable Auto Top-Up

Step 1: Navigate to Auto Top-Up Settings

From the WaymakerOne dashboard:

  1. Click "API Keys" in the left navigation
  2. Select the "Billing & Credits" tab
  3. Scroll to "Auto Top-Up Settings" section
  4. Click "Configure Auto Top-Up"

First time? You'll see a helpful explanation of how auto top-up works.

Step 2: Add Payment Method (If Needed)

If you haven't saved a payment method yet:

You'll see:

⚠️ Payment Method Required
Auto top-up requires a saved payment method for automatic charges.
Add a payment method to get started.

Action:

  1. Click "Add Payment Method"
  2. Complete the Stripe payment setup
  3. Return to auto top-up configuration

See Purchasing Credits for detailed payment method instructions.

Step 3: Enable Auto Top-Up

Toggle the "Enable Auto Top-Up" switch to ON.

Once enabled, you'll configure three settings:

  • Trigger threshold
  • Purchase amount
  • Monthly spending limit (optional)

Step 4: Set Trigger Threshold

What is this? The credit balance that triggers an automatic purchase.

Default: 500 credits ($5 worth)

How to choose:

  • Calculate your daily credit usage
  • Set threshold to 3-7 days of usage
  • Provides buffer before running out

Example calculations:

Low usage (10 credits/day):

Daily usage: 10 credits
7-day buffer: 10 × 7 = 70 credits
Recommended threshold: 100 credits

Medium usage (50 credits/day):

Daily usage: 50 credits
7-day buffer: 50 × 7 = 350 credits
Recommended threshold: 500 credits (default)

High usage (200 credits/day):

Daily usage: 200 credits
7-day buffer: 200 × 7 = 1,400 credits
Recommended threshold: 1,500 credits

💡 Tip: Check your API Usage Analytics to find your average daily consumption before setting the threshold.

Step 5: Set Purchase Amount

What is this? How many credits to purchase each time auto top-up triggers.

Default: 1,100 credits ($10)

Options:

  • $5 (500 credits)
  • $10 (1,100 credits) ← Recommended
  • $25 (2,750 credits)
  • $50 (5,500 credits)
  • $100 (11,500 credits)

How to choose:

  • Higher amounts include bonus credits (10-15% extra)
  • Should last 2-4 weeks based on usage
  • Balance between minimizing transaction frequency and cash flow

Example scenarios:

Light usage (~300 credits/week):

Weekly usage: 300 credits
$10 purchase: 1,100 credits
Lasts: ~3.5 weeks
Recommended: $10 purchase amount

Heavy usage (~1,000 credits/week):

Weekly usage: 1,000 credits
$25 purchase: 2,750 credits
Lasts: ~2.75 weeks
Recommended: $25 or $50 purchase amount

💡 Tip: Start with $10 and adjust based on how frequently auto top-up triggers.

Step 6: Set Monthly Spending Limit (Optional)

What is this? Maximum amount the system can automatically charge in a calendar month.

Default: No limit (unlimited auto top-up)

Why set a limit?

  • Budget control
  • Prevent runaway costs
  • Catch unexpected usage spikes
  • Peace of mind

Recommended limits:

Development/Testing:

Set limit: $25/month
Prevents accidental high usage during testing

Production (Low Volume):

Expected monthly cost: $50
Set limit: $75/month (50% buffer)

Production (High Volume):

Expected monthly cost: $200
Set limit: $300/month (50% buffer)

What happens when limit is reached?

  1. Auto top-up stops for the month
  2. You receive email alert
  3. API calls continue using remaining credits
  4. When credits run out, API returns 402 Payment Required
  5. Limit resets on the 1st of next month

💡 Tip: Set limit 50% higher than expected usage to allow for growth while preventing catastrophic costs.

Step 7: Review and Save

Configuration Summary:

Auto Top-Up Settings:
├── Status: Enabled ✅
├── Trigger Threshold: 500 credits
├── Purchase Amount: $10 (1,100 credits)
├── Monthly Limit: $100
└── Payment Method: •••• 4242

Click "Save Settings" to activate auto top-up.

✅ Auto top-up is now active and will check your balance hourly.

How Auto Top-Up Works

Execution Schedule

Hourly checks:

  • System reviews all accounts with auto top-up enabled
  • Runs at the top of each hour (:00 minutes)
  • Executes 24 times per day

Decision Logic

For each account, the system:

  1. Checks if enabled - Skip if auto top-up is off
  2. Checks balance - Is current balance ≤ threshold?
  3. Checks monthly limit - Would purchase exceed monthly limit?
  4. Checks payment method - Is valid payment method saved?
  5. Executes purchase - Charge via Stripe off-session payment
  6. Updates balance - Add credits immediately
  7. Sends notification - Email confirmation

Example flow:

Current balance: 450 credits
Threshold: 500 credits
Purchase amount: $10 (1,100 credits)
Monthly spend so far: $45
Monthly limit: $100

✅ Balance below threshold (450 ≤ 500)
✅ Monthly limit OK ($45 + $10 = $55 ≤ $100)
✅ Payment method valid
→ Charge $10 via Stripe
→ Add 1,100 credits
→ New balance: 1,550 credits
→ Send email: "Auto top-up: $10 charged, 1,100 credits added"

Email Notifications

Auto Top-Up Success

When: Credits successfully purchased via auto top-up Subject: "Waymaker One: Auto top-up successful - $10.00"

Email includes:

  • Credits purchased (1,100 credits)
  • Amount charged ($10.00)
  • New credit balance (1,550 credits)
  • Payment method used (•••• 4242)
  • Transaction timestamp
  • Link to purchase history

Monthly Limit Reached

When: Auto top-up attempt would exceed monthly spending limit Subject: "Waymaker One: Monthly spending limit reached"

Email includes:

  • Monthly limit amount ($100)
  • Current month's spend ($100)
  • Current credit balance (remaining credits)
  • Limit reset date (1st of next month)
  • Link to purchase credits manually
  • Link to adjust settings

⚠️ Action required: Purchase credits manually or wait until next month.

Payment Failed

When: Automatic charge fails (declined card, expired, etc.) Subject: "Waymaker One: Auto top-up payment failed"

Email includes:

  • Failure reason ("Card declined", "Card expired", etc.)
  • Current credit balance
  • Link to update payment method
  • Link to purchase credits manually
  • Support contact information

⚠️ Action required: Update payment method to resume auto top-up.

Monthly Spending Tracking

How It Works

Calendar month cycle:

  • Tracking period: 1st of month 00:00:00 UTC to last day 23:59:59 UTC
  • Resets automatically on the 1st
  • Counts only auto top-up purchases (manual purchases don't count)

View Current Spend

In the dashboard:

Auto Top-Up Status:
├── This Month's Spend: $45 / $100
├── Remaining Budget: $55
├── Resets: December 1, 2025
└── Last Purchase: Nov 15, 2025 (2 days ago)

Spend includes:

  • All auto top-up purchases this month
  • Does NOT include manual purchases
  • Does NOT include purchases from previous months

Spend Alerts

Alerts sent at:

  • 50% of limit - "You've used half your monthly auto top-up budget"
  • 80% of limit - "Approaching monthly auto top-up limit"
  • 100% of limit - "Monthly spending limit reached - auto top-up paused"

💡 Tip: Review usage when you receive the 50% alert to ensure budget is appropriate.

Managing Auto Top-Up

Temporarily Disable

To pause auto top-up without changing settings:

  1. Navigate to Auto Top-Up Settings
  2. Toggle "Enable Auto Top-Up" to OFF
  3. Settings are saved but not active

Use case: Pausing development for a few weeks and don't want automatic charges.

To re-enable: Toggle back to ON - all previous settings remain.

Modify Settings

To change threshold, amount, or limit:

  1. Navigate to Auto Top-Up Settings
  2. Click "Configure"
  3. Adjust any of the three settings
  4. Click "Save Settings"
  5. Changes take effect immediately

💡 Tip: No need to disable auto top-up to modify settings.

Disable Completely

To turn off auto top-up and clear settings:

  1. Navigate to Auto Top-Up Settings
  2. Toggle to OFF
  3. Click "Reset Settings" (optional - clears saved configuration)

Payment method remains saved for manual purchases.

Troubleshooting

Auto Top-Up Not Triggering

Balance dropped below threshold but no purchase occurred:

Possible causes:

  1. Monthly limit reached - Check if you've hit your monthly cap
  2. Payment method expired - Card expired since last successful charge
  3. Insufficient funds - Bank declined the charge
  4. Recently disabled - Auto top-up was turned off

Solutions:

  1. Check Auto Top-Up Status in dashboard
  2. Review email notifications for failure alerts
  3. Verify payment method is current
  4. Check monthly spending hasn't exceeded limit

Payment Declined During Auto Top-Up

Error: Card declined when attempting automatic purchase

Common causes:

  • Insufficient funds in account
  • Card expired
  • Daily spending limit exceeded
  • Card issuer flagged transaction

Solutions:

  1. Update payment method in Stripe
  2. Purchase credits manually to restore service
  3. Contact your bank if card is valid but keeps declining
  4. Add backup payment method for redundancy

System behavior:

  • Retries payment once after 1 hour
  • If second attempt fails, sends notification
  • Does NOT retry again (prevents multiple charges)
  • You must manually resolve before next month

Unexpected Charge

Received auto top-up charge but didn't expect it:

Check:

  1. Current credit balance before charge
  2. Configured threshold setting
  3. Recent API usage spike

Example scenario:

Threshold set: 500 credits
Expected usage: 50 credits/day
Actual usage: 200 credits/day (4x higher)

Result: Balance dropped faster than expected
→ Auto top-up triggered earlier than anticipated
→ Charge is legitimate based on actual usage

Prevention:

  • Monitor API Usage Analytics regularly
  • Set monthly spending limits
  • Receive usage spike alerts (future feature)

Monthly Limit Too Low

Auto top-up keeps hitting monthly limit:

Symptoms:

  • Multiple "monthly limit reached" emails
  • API service interruptions mid-month
  • Having to purchase credits manually

Solutions:

  1. Review actual usage in API Usage Analytics
  2. Calculate appropriate limit: 
    Average monthly usage: $75
Spike buffer (50%): $75 × 1.5 = $112.50
Recommended limit: $125/month
  3. Update monthly limit in settings
  4. Consider multiple auto top-up tiers (future feature)

Best Practices

1. Start Conservative

Recommended initial settings:

Threshold: 500 credits
Purchase amount: $10 (1,100 credits)
Monthly limit: $50

Why:

  • Tests auto top-up with low financial risk
  • Gives you data on actual usage patterns
  • Easy to adjust upward based on experience

After 1 month: Review and adjust based on:

  • How often auto top-up triggered
  • Whether limit was appropriate
  • Actual usage vs. expected usage

2. Match Purchase Amount to Usage

Calculate weeks of supply:

Weekly usage: 400 credits

$10 purchase (1,100 credits):
1,100 ÷ 400 = 2.75 weeks supply ← Good

$5 purchase (500 credits):
500 ÷ 400 = 1.25 weeks supply ← Too frequent

$25 purchase (2,750 credits):
2,750 ÷ 400 = 6.87 weeks supply ← May be too much

Recommendation: Aim for 2-4 weeks supply per purchase.

3. Set Appropriate Monthly Limits

Formula:

Expected monthly usage × 1.5 = Monthly limit

Example:

Expected: 2,000 credits/month = $20
With 50% buffer: $20 × 1.5 = $30
Set monthly limit: $30

Too tight: Constant limit alerts, service interruptions Too loose: Less budget protection, higher unexpected charges Just right: Rarely hit limit, catches true usage spikes

4. Monitor Regularly

Weekly checks:

  • Current credit balance
  • Recent auto top-up triggers
  • Pace toward monthly limit

Monthly reviews:

  • Total auto top-up spend
  • Compare to manual purchases
  • Adjust settings for next month

💡 Tip: Add a calendar reminder for monthly review.

5. Maintain Payment Method

Quarterly checks:

  • Payment method expiration date
  • Billing address accuracy
  • Bank account has sufficient funds
  • Card isn't approaching limit

Best practice: Add expiration dates to your calendar 60 days in advance.

Security Considerations

Off-Session Payments

Auto top-up uses Stripe off-session payments - charges without requiring you to be present.

Security measures:

  • ✅ Payment method must be explicitly saved for off-session use
  • ✅ At least one successful on-session payment required first
  • ✅ Charges limited by monthly spending cap
  • ✅ Email notifications for every charge
  • ✅ Detailed transaction logs

What you control:

  • When to enable/disable auto top-up
  • Maximum charge amount per trigger
  • Monthly spending ceiling
  • Payment method on file

Fraud Prevention

Built-in protections:

  • Maximum purchase amount ($100 per trigger)
  • Monthly spending limits
  • Email confirmation for every charge
  • Detailed transaction history
  • Ability to disable instantly

If you suspect unauthorized auto top-up:

  1. Immediately disable auto top-up
  2. Review transaction history
  3. Contact support@waymakerone.com
  4. Update payment method
  5. Review API usage for unexpected calls

Comparison: Auto Top-Up vs Manual

When to Use Auto Top-Up

✅ Best for:

  • Production applications
  • Consistent usage patterns
  • Teams who want hands-off billing
  • 24/7 services that can't tolerate downtime
  • High-volume API users

Advantages:

  • No service interruptions
  • Hands-free credit management
  • Takes advantage of bonus credits
  • Monthly spending limits for control
  • Email notifications keep you informed

When to Use Manual Purchases

✅ Best for:

  • Development and testing
  • Unpredictable usage patterns
  • Tight budget constraints requiring approval
  • Seasonal or sporadic API use
  • Learning credit consumption patterns

Advantages:

  • Complete control over every purchase
  • No automatic charges
  • Flexible timing
  • No setup required

Next Steps

Now that you understand auto top-up:

Related Articles

Questions about auto top-up? → Contact support@waymakerone.com