---
title: "Set S3 Auto Apply"
method: PUT
path: "/api/v1/ledger/s3/auto-apply"
tags: ["User APIs", "ledger-platform"]
---

# Set S3 Auto Apply

`PUT /api/v1/ledger/s3/auto-apply`

Turn automatic application on or off for one contract, or set its recurring amount.

Returns the refreshed apply surface, so the row the caller just changed comes back with its
new state and no second request is needed. The contract is looked up through the reservation
workflow's own ownership check, so another client's id is a 404 with no hint that it exists.

The reservations are recomputed before this responds, rather than being left to the hourly
sweep: switching auto-apply on and seeing no tokens appear until the next hour reads as a
broken control.

## Request body

- S3AutoApplySettingRequest — Change a contract's automatic-application settings. Every field optional, and at least one required — a request that changes nothing is a bug in the caller, not a no-op worth accepting. ``clear_recurring_tokens`` exists because a nullable ``recurring_tokens`` cannot express "go back to the computed default" and "leave the amount alone" with one field. Collapsing them would make toggling the switch off and on again silently wipe the amount the client chose.
  - `block_contract_id` string, uuid, required
  - `enabled` boolean, nullable
  - `recurring_tokens` union
    - number
    - string
  - `clear_recurring_tokens` boolean

## Response `200`

Successful Response

- S3UpcomingInvoicesResponse — The apply surface's header plus its rows. The three header figures come straight from ``S3BalanceSummaryResponse`` and keep its names, so the apply header can never disagree with the wallet tiles. ``reserved`` is what the wireframe labels "Applied to upcoming invoices" — the UI supplies that wording; the field stays ``reserved`` because no consumption has happened yet.
  - `available` string, required
  - `reserved` string, required
  - `remaining` string, required
  - `invoices` S3UpcomingInvoiceRow[], required
    - `block_contract_id` string, uuid, required
    - `dataset_id` string, required
    - `dataset_label` string, nullable
    - `cut` string, nullable
    - `period_seq` integer, required
    - `period_start` string, date-time, nullable
    - `send_date` string, date-time, nullable
    - `days_until_send` integer, nullable
    - `invoice_amount` string, required
    - `max_applicable_tokens` string, required
    - `applied_tokens` string, required
    - `net_due` string, required
    - `reservation_id` string, uuid, nullable
    - `editable` boolean
    - `auto_apply_enabled` boolean
    - `auto_default_tokens` string
    - `recurring_override_tokens` string, nullable
    - `applied_source` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)