---
title: "Enable or update auto-refill"
method: PUT
path: "/v1/billing/auto-refill"
tags: ["Billing"]
---

# Enable or update auto-refill

`PUT /v1/billing/auto-refill`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/billing/auto-refill`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `billing:manage`)

When the balance is below threshold_credits, the worker charges the pack on sale off-session, up to the monthly caps. Prices are listed at https://recruitmcp.com/pricing. A card must already be on file from a pack checkout. Credits are granted only after the payment succeeds. Account keys only.

Scope: `billing:manage`. Acts on the account; keys bound to a customer are refused.

## Headers

- `Idempotency-Key` string
- `RecruitMCP-Version` '2026-10-13'

## Request body

- AutoRefillInput
  - `enabled` boolean: Default true. False keeps the card and turns charging off.
  - `threshold_credits` integer, required: Refill when the balance is below this.
  - `max_refills_per_month` integer, required: Maximum charges in a UTC month.
  - `max_eur_per_month` integer, required: Euro cap for a UTC month. At least the price of one pack. Prices are listed at https://recruitmcp.com/pricing.

## Response `200`

Saved settings.

- AutoRefill
  - `object` 'auto_refill', required
  - `enabled` boolean, required
  - `threshold_credits` integer, nullable: Refill when the balance is below this. Null until it is set.
  - `max_refills_per_month` integer, nullable: Maximum charges in a UTC month.
  - `max_eur_per_month` integer, nullable: Euro cap for a UTC month.
  - `card_on_file` boolean, required: True after a pack checkout saves a card.
  - `refills_this_month` integer, required: Succeeded refills this UTC month. An in-flight charge is not counted until it is granted.
  - `amount_eur_this_month` integer, required
  - `disabled_reason` string, nullable: Why a failed charge turned auto-refill off.

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `409`: `conflict` (do not retry): The resource is in a state that refuses this change.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 5 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `409`
  - …1 more

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/billing/auto-refill/put.md)

---

[API](https://skmtc.dev/recruitmcp/apis/recruitmcp-api.md) · [All operations](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/revisions/ad27b35513a6?raw)