---
title: "Apply S3 Tokens"
method: POST
path: "/api/v1/ledger/s3/apply"
tags: ["User APIs", "ledger-platform"]
---

# Apply S3 Tokens

`POST /api/v1/ledger/s3/apply`

Apply tokens to one upcoming invoice.

Synchronous on purpose: the client has to learn *now* that an invoice is no longer
editable, rather than discovering later that their application silently did nothing.

Applying reserves the tokens; it writes no ledger transaction. The CONSUME lands only
when the invoice finalizes, which is what makes editing and un-applying free.

Returns 409 ``invoice_no_longer_editable`` once the credit line is on the Stripe draft.

## Request body

- S3ApplyRequest
  - `block_contract_id` string, uuid, required
  - `period_seq` integer, required
  - `amount` union, required
    - number
    - string
  - `idempotency_key` string, nullable

## Response `200`

Successful Response

- S3ApplyResponse — The applied row plus refreshed header figures, so the UI needs no second request.
  - `reservation_id` string, uuid, required
  - `block_contract_id` string, uuid, required
  - `period_seq` integer, required
  - `applied_tokens` string, required
  - `invoice_amount` string, required
  - `net_due` string, required
  - `available` string, required
  - `reserved` string, required
  - `remaining` string, required

## 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)