---
title: "Set the automatic payment ceiling"
method: PATCH
path: "/v1/billing/funding/ceiling"
---

# Set the automatic payment ceiling

`PATCH /v1/billing/funding/ceiling`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/billing/funding/ceiling`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Replaces the billing owner's exact calendar-month ceiling for automatic execution-credit charges, or turns automatic payment authority off with null. The expected revision prevents stale authority changes, and the Idempotency-Key makes retries converge. This command requires explicit agent approval because it changes payment authority. Tax and pending gross commitments consume the ceiling; manual purchases and project subscriptions do not. Refunds do not restore authority already used in that UTC month. USD 50 is the suggested editable default, not a platform maximum.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `automaticExecutionTopUpCeiling` object, nullable, required
    - `currency` 'USD', required
    - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
    - `scale` 6, required
  - `expectedRevision` integer, required

## Response `200`

Set the automatic payment ceiling

- object
  - `automaticExecutionTopUp` object, required
    - `ceiling` object, nullable, required
      - `currency` 'USD', required
      - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
      - `scale` 6, required
    - `currentPeriod` object, required
      - `end` string, required
      - `pending` object, required
        - `currency` 'USD', required
        - `microdollars` string, required
        - `scale` 6, required
      - `remaining` object, nullable, required
        - `currency` 'USD', required
        - `microdollars` string, required
        - `scale` 6, required
      - `settled` object, required
        - `currency` 'USD', required
        - `microdollars` string, required
        - `scale` 6, required
      - `start` string, required
    - `rule` object, required
      - `cooldownUntil` string, nullable, required
      - `desired` object, nullable, required
        - `ceiling` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
        - `credit` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
        - `triggerBelow` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
      - `effective` object, nullable, required
        - `ceiling` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
        - `credit` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
        - `triggerBelow` object, required
          - `currency` 'USD', required
          - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
          - `scale` 6, required
      - `setupUrl` string, uri
      - `state` 'disabled' | 'payment-method-required' | 'ready', required
      - `suspension` object, nullable, required
        - `at` string, required
        - `reason` 'authentication-required' | 'payment-failed', required
    - `revision` integer, required
  - `credit` object, required
    - `amountOwed` object, required
      - `currency` 'USD', required
      - `microdollars` string, required
      - `scale` 6, required
    - `available` object, required
      - `currency` 'USD', required
      - `microdollars` string, required
      - `scale` 6, required
    - `reserved` object, required
      - `currency` 'USD', required
      - `microdollars` string, required
      - `scale` 6, required
  - `freshness` object, required
    - `kind` 'authoritative', required
  - `paymentOperations` object[], required
    - `createdAt` string, required
    - `credit` object, required
      - `currency` 'USD', required
      - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
      - `scale` 6, required
    - `gross` object, nullable, required
      - `currency` 'USD', required
      - `microdollars` string, required
      - `scale` 6, required
    - `id` string, required
    - `kind` 'manual' | 'automatic', required
    - `paymentUrl` string, uri
    - `reason` string
    - `receiptUrl` string, uri
    - `state` 'pending' | 'paid' | 'failed' | 'authentication-required' | 'action-required' | 'canceled' | 'refunded' | 'reversed' | 'disputed', required
    - `tax` object, nullable, required
      - `currency` 'USD', required
      - `microdollars` string, required
      - `scale` 6, required
    - `taxStatus` 'calculated-at-checkout' | 'confirmed', required
    - `updatedAt` string, required
  - `subscribedProjectFees` object, required
    - `currency` 'USD', required
    - `microdollars` string, required
    - `scale` 6, required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing, test_to_live_escalation.
- `409`: Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict, state_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)