Skip to content
Start here

Billing

Validate Billing Address
billing.address_validation(BillingAddressValidationParams**kwargs) -> BillingAddressValidationResponse
POST/billing/address-validation
ModelsExpand Collapse
class BillingAddressValidationResponse: …
validated_addresses: Optional[List[ValidatedAddress]]

List of validated address suggestions.

address: Optional[str]

Validated address line 1.

address2: Optional[str]

Validated address line 2.

city: Optional[str]

Validated city.

country: Optional[str]

Validated country code.

state: Optional[str]

Validated state or province.

validation_code: Optional[str]

The validation result code.

zipcode: Optional[str]

Validated postal or zip code.

BillingSpend Policies

List Spend Policies
billing.spend_policies.list(SpendPolicyListParams**kwargs) -> SyncSinglePage[SpendPolicyListResponse]
GET/accounts/{account_id}/billing/spend-policies
Create Spend Policy
billing.spend_policies.create(SpendPolicyCreateParams**kwargs) -> SpendPolicyCreateResponse
POST/accounts/{account_id}/billing/spend-policies
Get Spend Policy
billing.spend_policies.get(strpolicy_id, SpendPolicyGetParams**kwargs) -> SpendPolicyGetResponse
GET/accounts/{account_id}/billing/spend-policies/{policy_id}
Update Spend Policy
billing.spend_policies.update(strpolicy_id, SpendPolicyUpdateParams**kwargs) -> SpendPolicyUpdateResponse
PUT/accounts/{account_id}/billing/spend-policies/{policy_id}
Delete Spend Policy
billing.spend_policies.delete(strpolicy_id, SpendPolicyDeleteParams**kwargs) -> SpendPolicyDeleteResponse
DELETE/accounts/{account_id}/billing/spend-policies/{policy_id}
ModelsExpand Collapse
class SpendPolicyListResponse: …

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"
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"
class SpendPolicyGetResponse: …

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"
class SpendPolicyUpdateResponse: …

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"
class SpendPolicyDeleteResponse: …
id: str

The unique identifier of the spend policy.

formatuuid

BillingSpend PoliciesAudit

List Spend Policy Audit Entries
billing.spend_policies.audit.list(strpolicy_id, AuditListParams**kwargs) -> SyncSinglePage[AuditListResponse]
GET/accounts/{account_id}/billing/spend-policies/{policy_id}/audit
ModelsExpand Collapse
class AuditListResponse: …

A state transition recorded when the policy was evaluated against the account’s balance.

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"
balance_cents: int

The account’s balance for the product at evaluation time, in US cents.

formatint64
billing_period_end: datetime

Exclusive end of the billing period that was evaluated.

formatdate-time
billing_period_start: datetime

Inclusive start of the billing period that was evaluated.

formatdate-time
created_at: datetime

When the entry was recorded.

formatdate-time
policy_version: int

The policy version that was evaluated.

formatint64
reason: str

A human-readable explanation of the trigger.

source: Literal["kafka", "policy_revision"]

What caused the evaluation. kafka means a balance update. policy_revision means a change to the policy.

One of the following:
"kafka"
"policy_revision"
threshold_cents: int

The policy threshold at evaluation time, in US cents.

formatint64
trigger: str

The trigger recorded at evaluation time. New evaluations record limit_reached when the balance reaches or exceeds the configured threshold. Earlier entries retain their recorded trigger.

BillingSpend PoliciesActivity

List Spend Policy Activity
billing.spend_policies.activity.list(ActivityListParams**kwargs) -> SyncCursorPaginationAfter[ActivityListResponse]
GET/accounts/{account_id}/billing/spend-policies/activity
ModelsExpand Collapse
class ActivityListResponse: …
id: str
action: Literal["created", "updated", "enabled", 2 more]
One of the following:
"created"
"updated"
"enabled"
"disabled"
"deleted"
actor: str

Verified actor identifier, unknown when absent, or trusted internal actor.

details: Details
after: Optional[DetailsAfter]

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[DetailsAfterCurrentState]

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[DetailsAfterCurrentStateEnforcement]

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"
before: Optional[DetailsBefore]

Prior configuration; null on creation or if a previous revision is unavailable.

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[DetailsBeforeCurrentState]

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[DetailsBeforeCurrentStateEnforcement]

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"
occurred_at: datetime
formatdate-time
policy_id: str

The unique identifier of the spend policy.

formatuuid
policy_version: int
formatint64
minimum1
product_id: str

BillingProfiles

Get Billing Profile
billing.profiles.get(ProfileGetParams**kwargs) -> ProfileGetResponse
GET/accounts/{account_id}/billing/profile
Create Billing Profile
billing.profiles.create(ProfileCreateParams**kwargs) -> ProfileCreateResponse
POST/accounts/{account_id}/billing/profile
Update Billing Profile
billing.profiles.update(ProfileUpdateParams**kwargs) -> ProfileUpdateResponse
PUT/accounts/{account_id}/billing/profile
Delete Billing Profile
billing.profiles.delete(ProfileDeleteParams**kwargs)
DELETE/accounts/{account_id}/billing/profile
Update Billing Email
billing.profiles.update_billing_email(ProfileUpdateBillingEmailParams**kwargs) -> ProfileUpdateBillingEmailResponse
PATCH/accounts/{account_id}/billing/profile
ModelsExpand Collapse
class ProfileGetResponse: …
id: Optional[str]

Billing item identifier tag.

maxLength32
account_type: Optional[str]
address: Optional[str]
address2: Optional[str]
balance: Optional[str]
card_expiry_month: Optional[int]
card_expiry_year: Optional[int]
card_number: Optional[str]
city: Optional[str]
company: Optional[str]
country: Optional[str]
created_on: Optional[datetime]
formatdate-time
device_data: Optional[str]
edited_on: Optional[datetime]
formatdate-time
enterprise_billing_email: Optional[str]
enterprise_primary_email: Optional[str]
first_name: Optional[str]
is_partner: Optional[bool]
last_name: Optional[str]
next_bill_date: Optional[datetime]
formatdate-time
payment_address: Optional[str]
payment_address2: Optional[str]
payment_city: Optional[str]
payment_country: Optional[str]
payment_email: Optional[str]
payment_first_name: Optional[str]
payment_gateway: Optional[str]
payment_last_name: Optional[str]
payment_nonce: Optional[str]
payment_state: Optional[str]
payment_zipcode: Optional[str]
primary_email: Optional[str]
state: Optional[str]
tax_id_type: Optional[str]
telephone: Optional[str]
validation_code: Optional[str]
vat: Optional[str]
zipcode: Optional[str]
class ProfileCreateResponse: …
id: Optional[str]

Billing item identifier tag.

maxLength32
account_type: Optional[str]
address: Optional[str]
address2: Optional[str]
balance: Optional[str]
card_expiry_month: Optional[int]
card_expiry_year: Optional[int]
card_number: Optional[str]
city: Optional[str]
company: Optional[str]
country: Optional[str]
created_on: Optional[datetime]
formatdate-time
device_data: Optional[str]
edited_on: Optional[datetime]
formatdate-time
enterprise_billing_email: Optional[str]
enterprise_primary_email: Optional[str]
first_name: Optional[str]
is_partner: Optional[bool]
last_name: Optional[str]
next_bill_date: Optional[datetime]
formatdate-time
payment_address: Optional[str]
payment_address2: Optional[str]
payment_city: Optional[str]
payment_country: Optional[str]
payment_email: Optional[str]
payment_first_name: Optional[str]
payment_gateway: Optional[str]
payment_last_name: Optional[str]
payment_nonce: Optional[str]
payment_state: Optional[str]
payment_zipcode: Optional[str]
primary_email: Optional[str]
state: Optional[str]
tax_id_type: Optional[str]
telephone: Optional[str]
validation_code: Optional[str]
vat: Optional[str]
zipcode: Optional[str]
class ProfileUpdateResponse: …
id: Optional[str]

Billing item identifier tag.

maxLength32
account_type: Optional[str]
address: Optional[str]
address2: Optional[str]
balance: Optional[str]
card_expiry_month: Optional[int]
card_expiry_year: Optional[int]
card_number: Optional[str]
city: Optional[str]
company: Optional[str]
country: Optional[str]
created_on: Optional[datetime]
formatdate-time
device_data: Optional[str]
edited_on: Optional[datetime]
formatdate-time
enterprise_billing_email: Optional[str]
enterprise_primary_email: Optional[str]
first_name: Optional[str]
is_partner: Optional[bool]
last_name: Optional[str]
next_bill_date: Optional[datetime]
formatdate-time
payment_address: Optional[str]
payment_address2: Optional[str]
payment_city: Optional[str]
payment_country: Optional[str]
payment_email: Optional[str]
payment_first_name: Optional[str]
payment_gateway: Optional[str]
payment_last_name: Optional[str]
payment_nonce: Optional[str]
payment_state: Optional[str]
payment_zipcode: Optional[str]
primary_email: Optional[str]
state: Optional[str]
tax_id_type: Optional[str]
telephone: Optional[str]
validation_code: Optional[str]
vat: Optional[str]
zipcode: Optional[str]
class ProfileUpdateBillingEmailResponse: …
id: Optional[str]

Billing item identifier tag.

maxLength32
account_type: Optional[str]
address: Optional[str]
address2: Optional[str]
balance: Optional[str]
card_expiry_month: Optional[int]
card_expiry_year: Optional[int]
card_number: Optional[str]
city: Optional[str]
company: Optional[str]
country: Optional[str]
created_on: Optional[datetime]
formatdate-time
device_data: Optional[str]
edited_on: Optional[datetime]
formatdate-time
enterprise_billing_email: Optional[str]
enterprise_primary_email: Optional[str]
first_name: Optional[str]
is_partner: Optional[bool]
last_name: Optional[str]
next_bill_date: Optional[datetime]
formatdate-time
payment_address: Optional[str]
payment_address2: Optional[str]
payment_city: Optional[str]
payment_country: Optional[str]
payment_email: Optional[str]
payment_first_name: Optional[str]
payment_gateway: Optional[str]
payment_last_name: Optional[str]
payment_nonce: Optional[str]
payment_state: Optional[str]
payment_zipcode: Optional[str]
primary_email: Optional[str]
state: Optional[str]
tax_id_type: Optional[str]
telephone: Optional[str]
validation_code: Optional[str]
vat: Optional[str]
zipcode: Optional[str]

BillingProfilesPayment Method

Create Payment Intent for Billing Profile
billing.profiles.payment_method.create(PaymentMethodCreateParams**kwargs) -> PaymentMethodCreateResponse
POST/accounts/{account_id}/billing/profile/payment-method
ModelsExpand Collapse
class PaymentMethodCreateResponse: …
client_secret: Optional[str]

The Stripe client secret for frontend payment method collection.

intent_type: Optional[str]

The type of Stripe intent created.

BillingUsage

Get Account Billable Usage Info (Version 1, Alpha)
Deprecated
billing.usage.paygo_info(UsagePaygoInfoParams**kwargs) -> UsagePaygoInfoResponse
GET/accounts/{account_id}/billable-usage/info
Get Account Billable Usage (Version 1, Alpha)
Deprecated
billing.usage.paygo(UsagePaygoParams**kwargs) -> UsagePaygoResponse
GET/accounts/{account_id}/billable-usage
Get Account Usage (Version 2, Alpha, Restricted)
Deprecated
billing.usage.get(UsageGetParams**kwargs) -> UsageGetResponse
GET/accounts/{account_id}/billable/usage
Get Account Billable Usage Info (Version 1, Alpha)
billing.usage.get_account_usage_info_v1(UsageGetAccountUsageInfoV1Params**kwargs) -> UsageGetAccountUsageInfoV1Response
GET/accounts/{account_id}/billable-usage/info
Get Account Billable Usage (Version 1, Alpha)
billing.usage.get_account_usage_v1(UsageGetAccountUsageV1Params**kwargs) -> UsageGetAccountUsageV1Response
GET/accounts/{account_id}/billable-usage
Get Account Usage (Version 2, Alpha, Restricted)
billing.usage.get_account_usage_v2(UsageGetAccountUsageV2Params**kwargs) -> UsageGetAccountUsageV2Response
GET/accounts/{account_id}/billable/usage
ModelsExpand Collapse
class UsagePaygoInfoResponse: …

Contains the usage info.

covered: bool

Indicates whether the account is covered.

subscriptions: List[Subscription]

List of subscriptions for the account.

id: str

The identifier for the Cloudflare subscription.

billing_cycle_anchor_timestamp: datetime

The subscription billing cycle anchor timestamp.

formatdate-time
start_timestamp: datetime

The subscription start timestamp.

formatdate-time
end_timestamp: Optional[datetime]

The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled.

formatdate-time
List[UsagePaygoResponseItem]

Contains the array of billable usage records.

billed_cost: float

The amount invoiced for this charge. PayGo is billed directly by Cloudflare, so this equals ContractedCost.

billing_account_id: str

The identifier of the account the charge is billed to (account tag).

billing_account_name: Optional[str]

The display name of the billing account. Null when the name could not be resolved.

billing_currency: str

Specifies the billing currency code (ISO 4217).

billing_period_start: datetime

Indicates the start of the billing period. There is no BillingPeriodEnd counterpart; see the known gaps described on this schema.

formatdate-time
charge_category: Literal["Usage"]

Describes the nature of the charge. Always “Usage” for this endpoint, which only returns metered usage.

charge_class: Optional[str]

Indicates whether the row corrects a previously invoiced billing period. Always null for this endpoint, which does not return corrections.

charge_description: Optional[str]

A human-readable summary of the charge.

charge_period_end: datetime

Indicates the end of the charge period.

formatdate-time
charge_period_start: datetime

Indicates the start of the charge period.

formatdate-time
consumed_quantity: float

Specifies the quantity consumed during this charge period.

consumed_unit: str

A display name for the unit of measurement used for the product (for example, “GB-months”, “GB-seconds”). May be empty when the unit is implicit in the service name.

contracted_cost: float

Specifies the cost for this charge period in the billing currency.

cumulated_contracted_cost: float

Specifies the cumulated cost for the billing period in the billing currency.

cumulated_pricing_quantity: int

Specifies the portion of usage that is actually subject to a unit price.

effective_cost: float

The amortized cost of the charge. PayGo has no upfront commitments, so this equals ContractedCost.

host_provider_name: str

The provider that hosts the infrastructure or platform the service runs on.

invoice_issuer_name: str

The entity that issues the invoice for this charge.

list_cost: float

The cost at published list prices, before any discount. PayGo has no commitment discounts, so this equals ContractedCost.

pricing_quantity: int

Specifies the pricing quantity for this charge period.

pricing_unit: str

The unit that PricingQuantity is expressed in. Unlike ConsumedUnit this is never empty; it falls back to “Count” when the service has no explicit unit.

service_name: str

Identifies the Cloudflare service.

service_provider_name: str

The provider of the purchased service.

service_family_name: Optional[str]

Identifies the product family for the Cloudflare service.

subscription_id: Optional[str]

The identifier for the Cloudflare subscription.

zone_id: Optional[str]

The identifier for the Cloudflare zone (zone tag).

zone_name: Optional[str]

The display name of the Cloudflare zone.

List[UsageGetResponseItem]

Contains the array of cost and usage records.

charge_category: Literal["Usage"]

Highest-level classification of a charge based on the nature of how it gets billed. Currently only “Usage” is supported.

charge_description: str

Self-contained summary of the charge’s purpose and price.

charge_frequency: Literal["Usage-Based"]

Indicates how often a charge occurs. Currently only “Usage-Based” is supported.

charge_period_end: datetime

Exclusive end of the time interval during which the usage was consumed.

formatdate-time
charge_period_start: datetime

Inclusive start of the time interval during which the usage was consumed.

formatdate-time
consumed_unit: str

Unit of measure for the consumed quantity (e.g., “GB”, “Requests”, “vCPU-Hours”).

host_provider_name: str

Name of the entity providing the underlying infrastructure or platform.

invoice_issuer_name: str

Name of the entity responsible for invoicing for the services consumed.

service_provider_name: str

Name of the entity that made the services available for purchase.

x_billable_metric_id: str

The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId.

billed_cost: Optional[float]

A charge serving as the basis for invoicing, inclusive of all reduced rates and discounts while excluding the amortization of upfront charges (one-time or recurring).

billing_account_id: Optional[str]

Public identifier of the Cloudflare account (account tag). Omitted when account is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by account: that usage is returned as its own record with no account.

billing_account_name: Optional[str]

Display name of the Cloudflare account. Omitted when account is not part of the requested grouping, and for usage measured at contract level.

billing_currency: Optional[str]

Currency that a charge was billed in (ISO 4217).

billing_period_end: Optional[datetime]

Exclusive end of the billing cycle that contains this usage record.

formatdate-time
billing_period_start: Optional[datetime]

Inclusive start of the billing cycle that contains this usage record.

formatdate-time
charge_class: Optional[Literal["Correction"]]

Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.

consumed_quantity: Optional[float]

Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations.

contracted_cost: Optional[float]

Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.

contracted_unit_price: Optional[float]

The agreed-upon unit price for a single PricingUnit of the associated billable metric, inclusive of negotiated discounts, if present, while excluding any other discounts.

effective_cost: Optional[float]

The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant, prepaid purchases (one-time or recurring) that covered the charge.

list_cost: Optional[float]

Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.

list_unit_price: Optional[float]

Suggested provider-published unit price for a single PricingUnit of the associated billable metric, exclusive of any discounts.

pricing_quantity: Optional[float]

Volume of a given service used or purchased, based on the PricingUnit.

pricing_unit: Optional[str]

Provider-specified measurement unit for determining unit prices, indicating how the provider rates measured usage after applying pricing rules like block pricing.

region_id: Optional[str]

Provider-assigned identifier for an isolated geographic area where a service is provided.

region_name: Optional[str]

Name of an isolated geographic area where a service is provided.

sub_account_id: Optional[str]

Unique identifier assigned to a grouping of services. For Cloudflare, this is the subscription or contract ID.

sub_account_name: Optional[str]

Name assigned to a grouping of services. For Cloudflare, this is the subscription or contract display name.

tags: Optional[Dict[str, Union[str, Literal[true]]]]

Tag values for the requested GroupBy keys. Omitted when GroupBy is not provided. Missing keys are omitted, and key-only tags are returned as boolean true. All other tag values are strings.

One of the following:
str
Literal[true]
x_billable_metric_name: Optional[str]

The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter.

x_product_category_name: Optional[str]

The product category the charge belongs to (e.g., “Developer”, “Cloudflare One”). Cloudflare extension; replaces FOCUS ServiceCategory.

x_product_family_id: Optional[str]

The unique identifier for the product family in the Cloudflare catalog. Cloudflare extension; replaces FOCUS ServiceId.

x_product_family_name: Optional[str]

The product family the charge belongs to (e.g., “R2”, “Workers”). Cloudflare extension; replaces FOCUS ServiceName.

x_zone_id: Optional[str]

The identifier for the Cloudflare zone (zone tag). Omitted when zone is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by zone. Cloudflare extension.

x_zone_name: Optional[str]

The display name of the Cloudflare zone. Omitted when zone is not part of the requested grouping, and for usage measured at contract level. Cloudflare extension.

class UsageGetAccountUsageInfoV1Response: …

Contains the usage info.

covered: bool

Indicates whether the account is covered.

subscriptions: List[Subscription]

List of subscriptions for the account.

id: str

The identifier for the Cloudflare subscription.

billing_cycle_anchor_timestamp: datetime

The subscription billing cycle anchor timestamp.

formatdate-time
start_timestamp: datetime

The subscription start timestamp.

formatdate-time
end_timestamp: Optional[datetime]

The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled.

formatdate-time
List[UsageGetAccountUsageV1ResponseItem]

Contains the array of billable usage records.

billed_cost: float

The amount invoiced for this charge. PayGo is billed directly by Cloudflare, so this equals ContractedCost.

billing_account_id: str

The identifier of the account the charge is billed to (account tag).

billing_account_name: Optional[str]

The display name of the billing account. Null when the name could not be resolved.

billing_currency: str

Specifies the billing currency code (ISO 4217).

billing_period_start: datetime

Indicates the start of the billing period. There is no BillingPeriodEnd counterpart; see the known gaps described on this schema.

formatdate-time
charge_category: Literal["Usage"]

Describes the nature of the charge. Always “Usage” for this endpoint, which only returns metered usage.

charge_class: Optional[str]

Indicates whether the row corrects a previously invoiced billing period. Always null for this endpoint, which does not return corrections.

charge_description: Optional[str]

A human-readable summary of the charge.

charge_period_end: datetime

Indicates the end of the charge period.

formatdate-time
charge_period_start: datetime

Indicates the start of the charge period.

formatdate-time
consumed_quantity: float

Specifies the quantity consumed during this charge period.

consumed_unit: str

A display name for the unit of measurement used for the product (for example, “GB-months”, “GB-seconds”). May be empty when the unit is implicit in the service name.

contracted_cost: float

Specifies the cost for this charge period in the billing currency.

cumulated_contracted_cost: float

Specifies the cumulated cost for the billing period in the billing currency.

cumulated_pricing_quantity: int

Specifies the portion of usage that is actually subject to a unit price.

effective_cost: float

The amortized cost of the charge. PayGo has no upfront commitments, so this equals ContractedCost.

host_provider_name: str

The provider that hosts the infrastructure or platform the service runs on.

invoice_issuer_name: str

The entity that issues the invoice for this charge.

list_cost: float

The cost at published list prices, before any discount. PayGo has no commitment discounts, so this equals ContractedCost.

pricing_quantity: int

Specifies the pricing quantity for this charge period.

pricing_unit: str

The unit that PricingQuantity is expressed in. Unlike ConsumedUnit this is never empty; it falls back to “Count” when the service has no explicit unit.

service_name: str

Identifies the Cloudflare service.

service_provider_name: str

The provider of the purchased service.

service_family_name: Optional[str]

Identifies the product family for the Cloudflare service.

subscription_id: Optional[str]

The identifier for the Cloudflare subscription.

zone_id: Optional[str]

The identifier for the Cloudflare zone (zone tag).

zone_name: Optional[str]

The display name of the Cloudflare zone.

List[UsageGetAccountUsageV2ResponseItem]

Contains the array of cost and usage records.

charge_category: Literal["Usage"]

Highest-level classification of a charge based on the nature of how it gets billed. Currently only “Usage” is supported.

charge_description: str

Self-contained summary of the charge’s purpose and price.

charge_frequency: Literal["Usage-Based"]

Indicates how often a charge occurs. Currently only “Usage-Based” is supported.

charge_period_end: datetime

Exclusive end of the time interval during which the usage was consumed.

formatdate-time
charge_period_start: datetime

Inclusive start of the time interval during which the usage was consumed.

formatdate-time
consumed_unit: str

Unit of measure for the consumed quantity (e.g., “GB”, “Requests”, “vCPU-Hours”).

host_provider_name: str

Name of the entity providing the underlying infrastructure or platform.

invoice_issuer_name: str

Name of the entity responsible for invoicing for the services consumed.

service_provider_name: str

Name of the entity that made the services available for purchase.

x_billable_metric_id: str

The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId.

billed_cost: Optional[float]

A charge serving as the basis for invoicing, inclusive of all reduced rates and discounts while excluding the amortization of upfront charges (one-time or recurring).

billing_account_id: Optional[str]

Public identifier of the Cloudflare account (account tag). Omitted when account is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by account: that usage is returned as its own record with no account.

billing_account_name: Optional[str]

Display name of the Cloudflare account. Omitted when account is not part of the requested grouping, and for usage measured at contract level.

billing_currency: Optional[str]

Currency that a charge was billed in (ISO 4217).

billing_period_end: Optional[datetime]

Exclusive end of the billing cycle that contains this usage record.

formatdate-time
billing_period_start: Optional[datetime]

Inclusive start of the billing cycle that contains this usage record.

formatdate-time
charge_class: Optional[Literal["Correction"]]

Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.

consumed_quantity: Optional[float]

Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations.

contracted_cost: Optional[float]

Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.

contracted_unit_price: Optional[float]

The agreed-upon unit price for a single PricingUnit of the associated billable metric, inclusive of negotiated discounts, if present, while excluding any other discounts.

effective_cost: Optional[float]

The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant, prepaid purchases (one-time or recurring) that covered the charge.

list_cost: Optional[float]

Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.

list_unit_price: Optional[float]

Suggested provider-published unit price for a single PricingUnit of the associated billable metric, exclusive of any discounts.

pricing_quantity: Optional[float]

Volume of a given service used or purchased, based on the PricingUnit.

pricing_unit: Optional[str]

Provider-specified measurement unit for determining unit prices, indicating how the provider rates measured usage after applying pricing rules like block pricing.

region_id: Optional[str]

Provider-assigned identifier for an isolated geographic area where a service is provided.

region_name: Optional[str]

Name of an isolated geographic area where a service is provided.

sub_account_id: Optional[str]

Unique identifier assigned to a grouping of services. For Cloudflare, this is the subscription or contract ID.

sub_account_name: Optional[str]

Name assigned to a grouping of services. For Cloudflare, this is the subscription or contract display name.

tags: Optional[Dict[str, Union[str, Literal[true]]]]

Tag values for the requested GroupBy keys. Omitted when GroupBy is not provided. Missing keys are omitted, and key-only tags are returned as boolean true. All other tag values are strings.

One of the following:
str
Literal[true]
x_billable_metric_name: Optional[str]

The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter.

x_product_category_name: Optional[str]

The product category the charge belongs to (e.g., “Developer”, “Cloudflare One”). Cloudflare extension; replaces FOCUS ServiceCategory.

x_product_family_id: Optional[str]

The unique identifier for the product family in the Cloudflare catalog. Cloudflare extension; replaces FOCUS ServiceId.

x_product_family_name: Optional[str]

The product family the charge belongs to (e.g., “R2”, “Workers”). Cloudflare extension; replaces FOCUS ServiceName.

x_zone_id: Optional[str]

The identifier for the Cloudflare zone (zone tag). Omitted when zone is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by zone. Cloudflare extension.

x_zone_name: Optional[str]

The display name of the Cloudflare zone. Omitted when zone is not part of the requested grouping, and for usage measured at contract level. Cloudflare extension.

BillingCredits

Get Account Credits
billing.credits.get(CreditGetParams**kwargs) -> CreditGetResponse
GET/accounts/{account_id}/billing/credits
ModelsExpand Collapse
class CreditGetResponse: …
confirmed_balance_cents: Optional[int]

The confirmed credit balance in cents.

formatint64
currency: Optional[str]

Currency of the credit balance.

days_remaining: Optional[int]

Days remaining until the credits expire.

formatint64
eligible: Optional[bool]

Whether the account is eligible to receive credits.

has_record: Optional[bool]

Whether a credit record exists for the account.

original_amount_cents: Optional[int]

The original credit amount in cents.

formatint64
percent_consumed: Optional[float]

Percentage of the original credit amount consumed.

formatdouble
projected_depletion_date: Optional[datetime]

Projected date when the credits will be depleted.

formatdate-time
valid_from: Optional[datetime]

When the credits become valid.

formatdate-time
valid_to: Optional[datetime]

When the credits expire.

formatdate-time

BillingHistory

Get Account Billing History
billing.history.list(HistoryListParams**kwargs) -> SyncV4PagePaginationArray[HistoryListResponse]
GET/accounts/{account_id}/billing/history
ModelsExpand Collapse
class HistoryListResponse: …
id: Optional[str]

Billing history item identifier.

action: Optional[str]

The billing item action.

amount: Optional[float]

The amount associated with this billing item.

amount_to_pay: Optional[float]

The amount remaining to pay.

currency: Optional[str]

The currency of the billing item.

description: Optional[str]

The billing item description.

external_invoice_id: Optional[str]

The external invoice identifier.

hosted_invoice_url: Optional[str]

URL to the hosted invoice.

invoice_id: Optional[str]

The associated invoice identifier.

occurred_at: Optional[datetime]

When the billing event occurred.

formatdate-time
receipt_id: Optional[str]

The associated receipt identifier.

source: Optional[str]

The source of the billing item.

source_invoice_id: Optional[str]

The source invoice identifier.

status: Optional[str]

The status of the billing item.

type: Optional[str]

The billing item type.

BillingBad Debt

Get Account Bad Debt
billing.bad_debt.get(BadDebtGetParams**kwargs) -> BadDebtGetResponse
GET/accounts/{account_id}/billing/bad-debt
ModelsExpand Collapse
class BadDebtGetResponse: …
already_paid: Optional[float]

Amount already paid towards the debt.

bad_debt_status: Optional[str]

The current bad debt status of the account.

invoices: Optional[List[Invoice]]

List of outstanding invoices contributing to bad debt.

id: Optional[str]

Billing history item identifier.

action: Optional[str]

The billing item action.

amount: Optional[float]

The amount associated with this billing item.

amount_to_pay: Optional[float]

The amount remaining to pay.

currency: Optional[str]

The currency of the billing item.

description: Optional[str]

The billing item description.

external_invoice_id: Optional[str]

The external invoice identifier.

hosted_invoice_url: Optional[str]

URL to the hosted invoice.

invoice_id: Optional[str]

The associated invoice identifier.

occurred_at: Optional[datetime]

When the billing event occurred.

formatdate-time
receipt_id: Optional[str]

The associated receipt identifier.

source: Optional[str]

The source of the billing item.

source_invoice_id: Optional[str]

The source invoice identifier.

status: Optional[str]

The status of the billing item.

type: Optional[str]

The billing item type.

total_debt_amount: Optional[float]

Total outstanding debt amount.

BillingUnpaid Invoice

Get Unpaid Invoices
billing.unpaid_invoice.get(UnpaidInvoiceGetParams**kwargs) -> UnpaidInvoiceGetResponse
GET/accounts/{account_id}/billing/unpaid-invoice
ModelsExpand Collapse
class UnpaidInvoiceGetResponse: …
invoices: Optional[List[Invoice]]

List of unpaid invoices.

id: Optional[str]

Billing history item identifier.

action: Optional[str]

The billing item action.

amount: Optional[float]

The amount associated with this billing item.

amount_to_pay: Optional[float]

The amount remaining to pay.

currency: Optional[str]

The currency of the billing item.

description: Optional[str]

The billing item description.

external_invoice_id: Optional[str]

The external invoice identifier.

hosted_invoice_url: Optional[str]

URL to the hosted invoice.

invoice_id: Optional[str]

The associated invoice identifier.

occurred_at: Optional[datetime]

When the billing event occurred.

formatdate-time
receipt_id: Optional[str]

The associated receipt identifier.

source: Optional[str]

The source of the billing item.

source_invoice_id: Optional[str]

The source invoice identifier.

status: Optional[str]

The status of the billing item.

type: Optional[str]

The billing item type.

BillingRate Plans

Get Rate Plan by Public Key
billing.rate_plans.get(strpublic_key) -> RatePlanGetResponse
GET/billing/rate_plans/{public_key}
ModelsExpand Collapse
class RatePlanGetResponse: …
id: Optional[str]

The uppercase rate plan public key.

components: Optional[List[Dict[str, object]]]

Pricing components that make up this rate plan.

currency: Optional[str]

Currency of the rate plan pricing.

public_name: Optional[str]

Human-readable description of the rate plan.