Auto top-up and alerts

A prepaid customer who runs out of credits in the middle of work is a support ticket. Two things prevent it: an auto top-up that buys credits for them, and alerts that tell them or you before the balance is gone.

Before you start

• A prepaid customer on a plan that allows top-ups. Prepaid and postpaid billing covers plans.
• A saved payment method on the customer, through a payment provider.

Auto top-up

An auto top-up is a standing rule on one customer: when a pool’s available balance falls to threshold, buy credits to bring it back to target_balance.

The plan has to allow it, and say how much a customer may commit:

{
  "plans": [
    {
      "key": "scale_monthly",
      "name": "Scale",
      "billing_mode": "prepaid",
      "currency": "usd",
      "interval": "month",
      "credit_type": "ai_credits",
      "pools": [{ "key": "included" }, { "key": "purchased" }],
      "top_up": {
        "unit_amount_decimal": "1",
        "minimum_credits": "1000",
        "maximum_credits": "100000",
        "pool": "purchased",
        "low_balance_at": "2000",
        "auto": {
          "allowed": true,
          "maximum_monthly_limit": { "amount": 500000, "currency": "usd" }
        }
      },
      "rates": [{ "event_name": "agent.task", "credits_per_unit": "10" }]
    }
  ]
}

Then set the rule for a customer, from your backend or from the customer view:

{
  "threshold": "500",
  "target_balance": "5000",
  "monthly_limit": { "amount": 20000, "currency": "usd" }
}

{
  "id": "atu_7bN3xV9qLc",
  "object": "auto_top_up",
  "customer": "cus_9sF2kq81LmQz",
  "credit_type": "ai_credits",
  "pool": "purchased",
  "enabled": true,
  "threshold": "500",
  "target_balance": "5000",
  "monthly_limit": { "amount": 20000, "currency": "usd" },
  "purchased_this_month": { "amount": 0, "currency": "usd" },
  "status": "active",
  "consecutive_failures": 0,
  "actor": { "type": "key", "id": "key_1xB6nW3dQz", "name": "Billing backend" },
  "livemode": false,
  "created_at": "2026-11-04T13:12:09Z"
}

PUT sets the rule, GET reads it and DELETE removes it. A customer has one auto top-up, and setting it again replaces the old one. The response names the pool it keeps full. The customer needs a saved payment method, from a checkout in payment_method mode or an earlier top-up. Without one, the request fails with invalid_state.

How a purchase works

1. After a consumption posts, if the pool’s available balance (after holds) is at or below threshold, Runledger starts a purchase of target_balance minus available, kept within the plan’s minimum_credits and maximum_credits.
2. It charges the customer’s saved payment method at their payment provider, the same way a top-up checkout does. Runledger never holds the money.
3. When the payment succeeds, a paid grant with source: auto_top_up is created, with the plan’s top-up price as its cost basis and the plan’s top_up.credits_expire_in, or one year when the plan sets none. auto_top_up.succeeded is sent.
4. There is at most one purchase in flight for a customer. A second can’t start until the first settles.

monthly_limit caps what automatic purchases may cost in a calendar month (UTC). It limits purchases, not consumption: when the next purchase would pass it, Runledger buys what fits, if that meets the minimum, and otherwise buys nothing. A customer whose limit has run out is denied when their balance does, like any customer without credits.

When a payment fails

A failed payment sends auto_top_up.failed and counts as a failure. The next consumption that finds the balance low tries again. After three failures in a row the rule stops: status becomes disabled, auto_top_up.disabled is sent, and an auto_top_up.disabled notification rule emails the people you chose. A success resets the count. Set the rule again with PUT to turn it back on.

Alerts without buying

enabled: false keeps the rule and buys nothing. balance.low still goes out when the balance falls to its threshold. That is how a customer asks for a low-balance warning without letting anything be charged.

Sandbox

There is no card in the sandbox, so a purchase stays pending until you settle it with POST /v1/test_helpers/auto_top_ups/{id}/resolve and an outcome of succeeded or failed. The auto_top_up scenario in the MCP server’s run_scenario tool runs a pool below its threshold and settles it both ways. Use it to see the retry and the disable after three failures.

Creating a customer’s auto top-up rule, changing it and turning it off each write an audit event with the actor (auto_top_up.created, auto_top_up.updated, auto_top_up.turned_off), whether the customer, an operator or an agent did it.

Alerts

Runledger sends alerts about a customer’s balance, limits and credits as webhooks to your endpoints, and you decide how to reach the person: an email, an in-product banner or a message to an agent. Runledger never emails your end customers. Notification rules are for your own team and don’t carry these alerts. The events are thin like every other event. The context field names the customer, member_id, team_id, pool, allowance, limit and threshold, so you can write the message without another call.

Each threshold fires once per window or period, and balance.low once each time the balance falls below its level. A customer can set their own auto top-up on the customer view. The limit a customer sets there blocks and has no alert_at, so thresholds of the customer’s choosing come from a limit you set for them through the API with set_by: customer.

{
  "id": "whe_3rT8nB5vQp",
  "object": "webhook_event",
  "type": "usage.threshold_reached",
  "api_version": "2026-10-18",
  "related_object": {
    "id": "cus_9sF2kq81LmQz",
    "object": "usage_summary",
    "url": "/v1/customers/cus_9sF2kq81LmQz/usage_summary"
  },
  "context": {
    "customer": "cus_9sF2kq81LmQz",
    "allowance": "weekly",
    "pool": "included",
    "threshold": "0.8",
    "window_start": "2026-11-02T00:00:00Z",
    "resets_at": "2026-11-09T00:00:00Z"
  },
  "reason": { "type": "request", "request_id": "req_7Hc2Lq0vTz8d", "idempotency_key": "conv_4821-step-7" },
  "livemode": false,
  "created_at": "2026-11-06T09:41:03Z"
}

Fetch related_object.url for the current numbers, and deduplicate on id like any other event. See Webhooks.

API reference

Set, retrieve and delete a customer’s auto top-up.

Next steps

• Spend limits cap the money value of work in a period, a separate test from the balance.
• Credit expiry and breakage covers how long purchased credits last: one year by default.
• Customer view lets customers set their own top-up.
• Webhooks covers verifying the events these alerts send.