Skip to content
Cloudflare API
Start here
API Reference
Billing
Spend Policies

Create Spend Policy

billing.spend_policies.create(SpendPolicyCreateParams**kwargs) -> SpendPolicyCreateResponse
POST/accounts/{account_id}/billing/spend-policies

Creates a spend policy. Each account can have only one enabled usage_block policy per product. A second one returns 409. There is no limit on notification policies.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
ParametersExpand Collapse
account_id: str

Represents a Cloudflare resource identifier tag.

maxLength32
action: Literal["notification", "usage_block"]

The action taken when the threshold is reached. notification sends an email to notification_email. usage_block blocks further usage of the product until the end of the billing period. Raising the threshold above the current balance, disabling the policy, or deleting it lifts the block early.

One of the following:
"notification"
"usage_block"
enabled: bool

Whether the policy is evaluated.

name: str

Display name of the policy. After surrounding whitespace is trimmed, it must be 1 to 200 bytes long. The value is stored as sent, untrimmed.

minLength1
product_id: Literal["workers", "durable_objects"]

The product the policy applies to: workers or durable_objects. Each product’s balance and policies are separate. Both products support notification and usage_block policies on create and update.

One of the following:
"workers"
"durable_objects"
threshold_cents: int

The spend threshold for the current billing period, in US cents. Must be greater than zero.

formatint64
minimum1
notification_email: Optional[str]

Email address that receives notifications. Required when action is notification. When set, it must be a bare address (user@example.com); display-name forms such as Name <user@example.com> are rejected.

formatemail
ReturnsExpand Collapse
class SpendPolicyCreateResponse: …

A spend policy.

id: str

The unique identifier of the spend policy.

formatuuid
account_id: int

Internal numeric ID of the account that owns the policy. This is not the account tag used in the path.

formatint64
action: Literal["notification", "usage_block"]

The action taken when the threshold is reached. notification sends an email to notification_email. usage_block blocks further usage of the product until the end of the billing period. Raising the threshold above the current balance, disabling the policy, or deleting it lifts the block early.

One of the following:
"notification"
"usage_block"
enabled: bool

Whether the policy is evaluated.

name: str

Display name of the policy.

notification_email: str

Email address that receives notifications. An empty string when none is set.

product_id: Literal["workers", "durable_objects"]

The product the policy applies to: workers or durable_objects. Each product’s balance and policies are separate. Both products support notification and usage_block policies on create and update.

One of the following:
"workers"
"durable_objects"
threshold_cents: int

The spend threshold for the current billing period, in US cents.

formatint64
version: int

Optimistic-concurrency version. It starts at 1 and goes up by one on every update or delete. This value is also returned in ETag.

formatint64
minimum1
current_state: Optional[CurrentState]

Read-only state on list/get responses, evaluated from the latest owning projector snapshot at request time, independently of the API replica. Configuration enabled/version/ETag do not change when a cycle rolls over. Audit history remains unchanged. Missing during a rolling upgrade or on mutation responses; clients must treat missing state as unavailable. Balances are asynchronous estimates, not a synchronous usage read.

balance_cents: Optional[int]
formatint64
billing_period_end: Optional[datetime]
formatdate-time
billing_period_start: Optional[datetime]
formatdate-time
enforcement: Optional[CurrentStateEnforcement]

Durable desired cap and delivery bookkeeping for this policy, or null if no owned effect exists. Separate from threshold evaluation: pending/leased/retry can lag the new billing period. Succeeded with equal generations means delivery completed, not an EWC readback.

applied_generation: int
formatint64
delivery_status: Literal["pending", "leased", "retry", "succeeded"]
One of the following:
"pending"
"leased"
"retry"
"succeeded"
desired_generation: int
formatint64
desired_state: Literal["active", "inactive"]
One of the following:
"active"
"inactive"
expires_at: Optional[datetime]
formatdate-time
evaluated_at: datetime

Evaluation time; not the timestamp of the latest usage event.

formatdate-time
status: Literal["disabled", "no_current_period", "unavailable", 2 more]

Threshold evaluation, not proof of an edge cap. No current active period yields no_current_period for enabled policies; failed aggregate reads yield unavailable for enabled policies. Disabled policies report disabled. Neither no_current_period nor unavailable implies a zero balance or below-limit state. Operators may disable current-state reads, in which case current_state is omitted.

One of the following:
"disabled"
"no_current_period"
"unavailable"
"below_limit"
"limit_reached"

Create Spend Policy

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
spend_policy = client.billing.spend_policies.create(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    action="notification",
    enabled=True,
    name="Durable Objects alert",
    product_id="durable_objects",
    threshold_cents=100,
    notification_email="billing@example.com",
)
print(spend_policy.id)
{
  "errors": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "messages": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "result": {
    "id": "6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d",
    "account_id": 1234567,
    "action": "notification",
    "enabled": true,
    "name": "Workers cap",
    "notification_email": "billing@example.com",
    "product_id": "workers",
    "threshold_cents": 100,
    "version": 1,
    "current_state": {
      "balance_cents": 0,
      "billing_period_end": "2019-12-27T18:11:19.117Z",
      "billing_period_start": "2019-12-27T18:11:19.117Z",
      "enforcement": {
        "applied_generation": 0,
        "delivery_status": "pending",
        "desired_generation": 0,
        "desired_state": "active",
        "expires_at": "2019-12-27T18:11:19.117Z"
      },
      "evaluated_at": "2019-12-27T18:11:19.117Z",
      "status": "disabled"
    }
  },
  "success": true
}
Returns Examples
{
  "errors": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "messages": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "result": {
    "id": "6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d",
    "account_id": 1234567,
    "action": "notification",
    "enabled": true,
    "name": "Workers cap",
    "notification_email": "billing@example.com",
    "product_id": "workers",
    "threshold_cents": 100,
    "version": 1,
    "current_state": {
      "balance_cents": 0,
      "billing_period_end": "2019-12-27T18:11:19.117Z",
      "billing_period_start": "2019-12-27T18:11:19.117Z",
      "enforcement": {
        "applied_generation": 0,
        "delivery_status": "pending",
        "desired_generation": 0,
        "desired_state": "active",
        "expires_at": "2019-12-27T18:11:19.117Z"
      },
      "evaluated_at": "2019-12-27T18:11:19.117Z",
      "status": "disabled"
    }
  },
  "success": true
}