Auto top-up

Automatic balance replenishment: when the balance drops below a threshold, the configured amount is charged from the saved payment method. Available in API v2 only — there is no v1 counterpart.

Requires the feature to be enabled on the server. When it is off, both endpoints return Auto top-up is not available.

Endpoint:

This request returns the current auto top-up configuration and the last trigger result.

GEThttps://proxy-seller.com/personal/api/v2/{YourApiKey}/balance/autotopup/get

Path parameters

Name	Value	Description
Authorization	`<Your_API_Key>`	Your personal API key (How to get)

Example

https://proxy-seller.com/personal/api/v2/fj4948ffhg58gh843gh/balance/autotopup/get

Response

{
    "status": "success",
    "data": {
        "configured": true,
        "enabled": true,
        "state": "ACTIVE",
        "threshold": 10,
        "amount": 25,
        "subscriptionId": "sub_01hx9k2m4p",
        "paymentMethod": {
            "id": "sub_01hx9k2m4p",
            "status": "active",
            "paymentMethod": "card",
            "brand": "visa",
            "last4": "1234",
            "exp": "05/2027"
        },
        "dailyCountCap": 5,
        "monthlyAmountCap": 500,
        "failCount": 0,
        "lastAttemptAt": "2026-08-14T09:12:44.000+00:00",
        "lastEvent": {
            "status": "SUCCEEDED",
            "amount": 25,
            "at": "2026-08-14T09:12:46.000+00:00",
            "reason": null
        }
    },
    "errors": []
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Auto top-up is not available",
            "code": 49,
            "customData": null
        }
    ]
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Error api key",
            "code": 503,
            "customData": null
        },
        {
            "message": "IP not allowed",
            "code": 503,
            "customData": null
        },
        {
            "message": "Request limit reached",
            "code": 503,
            "customData": null
        }
    ]
}

Change settings

Endpoint:

This request updates the auto top-up configuration. Partial update: any field you omit keeps its stored value, so to change only the threshold it is enough to send threshold.

POSThttps://proxy-seller.com/personal/api/v2/{YourApiKey}/balance/autotopup/set

Path parameters

Name	Value	Description
Authorization	`<Your_API_Key>`	Your personal API key (How to get)

Request body

Name	Type	Description
enabled	Boolean	Switch auto top-up on or off
threshold	Number	Charge when the balance falls below this value. Minimum `1`
amount	Number	Amount of a single top-up. Minimum `5`, and must be greater than or equal to `threshold`
subscriptionId	String	Payment method to charge, taken from `paymentMethod.id`. Optional while only one card is available
dailyCountCap	Number	Your own stricter limit of top-ups per 24h. Minimum `1`
monthlyAmountCap	Number	Your own limit of the total amount per 30 days. Must be greater than or equal to `amount`

Example

https://proxy-seller.com/personal/api/v2/fj4948ffhg58gh843gh/balance/autotopup/set

Response

{
    "status": "success",
    "data": {
        "configured": true,
        "enabled": true,
        "state": "ACTIVE",
        "threshold": 10,
        "amount": 25,
        "subscriptionId": "sub_01hx9k2m4p",
        "paymentMethod": {
            "id": "sub_01hx9k2m4p",
            "status": "active",
            "paymentMethod": "card",
            "brand": "visa",
            "last4": "4242",
            "exp": "05/2027"
        },
        "dailyCountCap": 5,
        "monthlyAmountCap": 500,
        "failCount": 0,
        "lastAttemptAt": null,
        "lastEvent": {
            "status": "SETTINGS_SAVED",
            "amount": null,
            "at": "2026-08-14T10:03:11.000+00:00",
            "reason": "enabled: false -> true"
        }
    },
    "errors": []
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Top-up amount must be #min_amount# or more",
            "code": 51,
            "customData": {
                "minAmount": 5
            }
        }
    ]
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Top-up amount must cover the threshold, otherwise it will trigger again",
            "code": 52,
            "customData": null
        }
    ]
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Auto top-up requires a saved payment method",
            "code": 53,
            "customData": null
        }
    ]
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Your saved card has expired — update it to enable auto top-up",
            "code": 56,
            "customData": null
        }
    ]
}

{
    "status": "error",
    "data": null,
    "errors": [
        {
            "message": "Threshold must be #min_threshold# or more",
            "code": 50,
            "customData": {
                "minThreshold": 1
            }
        }
    ]
}

Validation runs against the merged result, not against the request alone. Sending threshold on its own is still rejected if the stored amount ends up lower than the new threshold.
The pause after a series of failed charges is cleared only when enabled: true is sent explicitly. Editing other fields on a paused configuration leaves the pause in place.
Effective caps also apply when the user set none: 5 top-ups per 24h and 500 per rolling 30 days.

Endpoint:

Path parameters

Example

Response

Change settings

Endpoint:

Path parameters

Request body

Example

Response

On this page