Enable or disable recurring auto top-up

Server URLloading...

PUT

/v1/billing/wallet/auto-topup

Send

Authorization

Body

Sets your auto top-up state directly: send the desired configuration and the service converges to it. A single PUT covers both enabling and disabling, since the feature has one on/off bit plus the chosen top-up option.

To enable, send {"enabled": true, "stripe_product_id": "..."}. Each successful recurring charge credits your wallet with that amount. To disable, send {"enabled": false}; this cancels the recurring charge and clears the auto top-up configuration.

The call is idempotent: disabling when already off returns the current state without a payment-processor round-trip.

The chosen option must meet your plan's min_topup_cents floor. Under PAYG that floor is NULL, so every option ($5–$100) is accepted, there is no tier-minimum floor.

Below-minimum options are rejected at enable time with 402 BELOW_MINIMUM_CREDIT. Enabling when already enabled returns 409 CONFLICT. An unknown or unavailable option returns 422 VALIDATION_FAILED with details.stripe_product_id. An organization without a base subscription returns 402 NO_PLAN.

Requires the billing:write scope.

Response Body

curl -X PUT "https://example.com/v1/billing/wallet/auto-topup" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "stripe_product_id": "prod_UNRcByVTMJ9LH2"  }'

{
  "success": true,
  "data": {
    "enabled": true,
    "auto_topup_amount_cents": 2000,
    "auto_topup_threshold_cents": 2000,
    "stripe_product_id": "prod_UNRcByVTMJ9LH2",
    "auto_topup_stripe_subscription_id": "sub_1NbCxYJh3ZgY8a",
    "next_charge_at": "2026-05-26T12:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "authentication failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "BELOW_MINIMUM_CREDIT",
    "message": "balance below tier minimum",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "missing required scope",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "auto-topup already enabled for org",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "validation failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
    "details": {
      "to": "must be E.164",
      "body": "must be 1..1600 chars"
    }
  }
}