# Billing # Profiles ## Billing Profile Details `billing.profiles.get(ProfileGetParams**kwargs) -> ProfileGetResponse` **get** `/accounts/{account_id}/billing/profile` Gets the current billing profile for the account. ### Parameters - `account_id: str` Identifier ### Returns - `class ProfileGetResponse: …` - `id: Optional[str]` Billing item identifier tag. - `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]` - `device_data: Optional[str]` - `edited_on: Optional[datetime]` - `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]` - `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]` - `use_legacy: Optional[bool]` - `validation_code: Optional[str]` - `vat: Optional[str]` - `zipcode: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) profile = client.billing.profiles.get( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(profile.id) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "b69a9f3492637782896352daae219e7d", "account_type": "type", "address": "123 Main Street", "address2": "Apt 1", "balance": "0", "card_expiry_month": 12, "card_expiry_year": 2099, "card_number": "4242424242424242", "city": "Anytown", "company": "Company", "country": "Anycountry", "created_on": "2014-03-01T12:21:59.3456Z", "device_data": "sample_data", "edited_on": "2014-03-01T12:21:59.3456Z", "enterprise_billing_email": "johndoe@gmail.com", "enterprise_primary_email": "johndoe@gmail.com", "first_name": "John", "is_partner": false, "last_name": "Doe", "next_bill_date": "2014-03-01T12:21:59.3456Z", "payment_address": "123 Main Street", "payment_address2": "Apt 1", "payment_city": "Anytown", "payment_country": "Anycountry", "payment_email": "johndoe@gmail.com", "payment_first_name": "John", "payment_gateway": "gateway", "payment_last_name": "Doe", "payment_nonce": "abc123", "payment_state": "state", "payment_zipcode": "12345", "primary_email": "johndoe@gmail.com", "state": "AnyState", "tax_id_type": "type", "telephone": "1234567899", "use_legacy": false, "validation_code": "1111", "vat": "GB123456789", "zipcode": "12345" }, "success": true } ``` ## Domain Types ### Profile Get Response - `class ProfileGetResponse: …` - `id: Optional[str]` Billing item identifier tag. - `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]` - `device_data: Optional[str]` - `edited_on: Optional[datetime]` - `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]` - `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]` - `use_legacy: Optional[bool]` - `validation_code: Optional[str]` - `vat: Optional[str]` - `zipcode: Optional[str]` # Usage ## Get PayGo Account Billable Usage Info (Version 1, Alpha) `billing.usage.paygo_info(UsagePaygoInfoParams**kwargs) -> UsagePaygoInfoResponse` **get** `/accounts/{account_id}/paygo-usage-info` Returns high-level usage information for the account, including coverage, and subscription metadata. ### Parameters - `account_id: str` Represents a Cloudflare resource identifier tag. ### Returns - `class UsagePaygoInfoResponse: …` Contains the paygo 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. - `start_timestamp: datetime` The subscription start timestamp. - `end_timestamp: Optional[datetime]` The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.billing.usage.paygo_info( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.covered) ``` #### Response ```json { "errors": [ { "message": "message", "code": 0 } ], "messages": [ { "message": "message", "code": 0 } ], "result": { "covered": true, "subscriptions": [ { "id": "3F3CD4CQ6N7FXO7IK6NVFJBOYA", "billing_cycle_anchor_timestamp": "2023-01-01T00:00:00Z", "start_timestamp": "2023-01-01T00:00:00Z", "end_timestamp": "2023-12-31T23:59:59Z" } ] }, "success": true } ``` ## Get PayGo Account Billable Usage (Version 1, Alpha) `billing.usage.paygo(UsagePaygoParams**kwargs) -> UsagePaygoResponse` **get** `/accounts/{account_id}/paygo-usage` Returns billable usage data for PayGo (self-serve) accounts. When no query parameters are provided, returns usage for the current billing period. ### Parameters - `account_id: str` Represents a Cloudflare resource identifier tag. - `from_: Optional[Union[null, null]]` Start date for the usage query (ISO 8601). - `to: Optional[Union[null, null]]` End date for the usage query (ISO 8601). ### Returns - `List[UsagePaygoResponseItem]` Contains the array of billable usage records. - `billing_currency: str` Specifies the billing currency code (ISO 4217). - `billing_period_start: datetime` Indicates the start of the billing period. - `charge_period_end: datetime` Indicates the end of the charge period. - `charge_period_start: datetime` Indicates the start of the charge period. - `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 cumulated pricing quantity for the billing period. - `pricing_quantity: int` Specifies the pricing quantity for this charge period. - `service_name: str` Identifies the Cloudflare 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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.billing.usage.paygo( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response) ``` #### Response ```json { "errors": [ { "message": "message", "code": 0 } ], "messages": [ { "message": "message", "code": 0 } ], "result": [ { "BillingCurrency": "USD", "BillingPeriodStart": "2025-02-01T00:00:00Z", "ChargePeriodEnd": "2025-02-02T00:00:00Z", "ChargePeriodStart": "2025-02-01T00:00:00Z", "ConsumedQuantity": 150000, "ConsumedUnit": "GB-months", "ContractedCost": 0.75, "CumulatedContractedCost": 2.25, "CumulatedPricingQuantity": 4500000, "PricingQuantity": 150000, "ServiceName": "Workers Standard", "ServiceFamilyName": "Workers", "SubscriptionId": "3F3CD4CQ6N7FXO7IK6NVFJBOYA", "ZoneId": "023e105f4ecef8ad9ca31a8372d0c353", "ZoneName": "example.com" } ], "success": true } ``` ## Get Account Usage (Version 2, Alpha, Restricted) `billing.usage.get(UsageGetParams**kwargs) -> UsageGetResponse` **get** `/accounts/{account_id}/billable/usage` Returns cost and usage data for a single Cloudflare account, aligned with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/) Cost and Usage dataset specification. Each record represents one billable metric for one account on one day. This includes all metered usage, including usage that falls within free-tier allowances and may result in zero cost. **Note:** Cost and pricing fields are not yet populated and will be absent from responses until billing integration is complete. When `from` and `to` are omitted, defaults to the start of the current month through today. The maximum date range is 31 days. ### Parameters - `account_id: str` Represents a Cloudflare resource identifier tag. - `from_: Optional[Union[null, null]]` Start date for the usage query (ISO 8601). Required if `to` is set. When omitted along with `to`, defaults to the start of the current month. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days. - `metric_id: Optional[Sequence[str]]` Filter results by one or more billable metric ids. Repeat the parameter to filter by multiple metrics. Maximum 10 values. - `to: Optional[Union[null, null]]` End date for the usage query (ISO 8601). Required if `from` is set. When omitted along with `from`, defaults to today. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days. ### Returns - `List[UsageGetResponseItem]` Contains the array of cost and usage records. - `billing_account_id: str` Public identifier of the Cloudflare account (account tag). - `billing_account_name: str` Display name of the Cloudflare account. - `charge_category: Literal["Usage"]` Highest-level classification of a charge based on the nature of how it gets billed. Currently only "Usage" is supported. - `"Usage"` - `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. - `"Usage-Based"` - `charge_period_end: datetime` Exclusive end of the time interval during which the usage was consumed. - `charge_period_start: datetime` Inclusive start of the time interval during which the usage was consumed. - `consumed_quantity: float` Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations. - `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_name: str` The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter. - `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_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. - `billing_period_start: Optional[datetime]` Inclusive start of the billing cycle that contains this usage record. - `charge_class: Optional[Literal["Correction"]]` Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period. - `"Correction"` - `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. - `x_billable_metric_id: Optional[str]` The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId. - `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). Cloudflare extension. - `x_zone_name: Optional[str]` The display name of the Cloudflare zone. Cloudflare extension. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) usages = client.billing.usage.get( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(usages) ``` #### Response ```json { "errors": [ { "message": "message", "code": 0 } ], "messages": [ { "message": "message", "code": 0 } ], "result": [ { "BillingAccountId": "023e105f4ecef8ad9ca31a8372d0c353", "BillingAccountName": "My Account", "ChargeCategory": "Usage", "ChargeDescription": "Workers Standard Requests — daily usage", "ChargeFrequency": "Usage-Based", "ChargePeriodEnd": "2025-05-02T00:00:00Z", "ChargePeriodStart": "2025-05-01T00:00:00Z", "ConsumedQuantity": 150000, "ConsumedUnit": "Requests", "HostProviderName": "Cloudflare", "InvoiceIssuerName": "Cloudflare", "ServiceProviderName": "Cloudflare", "x_BillableMetricName": "Workers Standard Requests", "BilledCost": 0, "BillingCurrency": "USD", "BillingPeriodEnd": "2025-06-01T00:00:00Z", "BillingPeriodStart": "2025-05-01T00:00:00Z", "ChargeClass": "Correction", "ContractedCost": 0.75, "ContractedUnitPrice": 0.000005, "EffectiveCost": 0, "ListCost": 0.75, "ListUnitPrice": 0.000005, "PricingQuantity": 150000, "PricingUnit": "Requests", "RegionId": "EEUR", "RegionName": "Eastern Europe", "SubAccountId": "c9bd752d-9ca8-411d-b804-be44a758057f", "SubAccountName": "My Subscription", "x_BillableMetricId": "workers_standard_requests", "x_ProductFamilyName": "Workers", "x_ZoneId": "023e105f4ecef8ad9ca31a8372d0c353", "x_ZoneName": "example.com" } ], "success": true } ``` ## Domain Types ### Usage Paygo Info Response - `class UsagePaygoInfoResponse: …` Contains the paygo 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. - `start_timestamp: datetime` The subscription start timestamp. - `end_timestamp: Optional[datetime]` The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled. ### Usage Paygo Response - `List[UsagePaygoResponseItem]` Contains the array of billable usage records. - `billing_currency: str` Specifies the billing currency code (ISO 4217). - `billing_period_start: datetime` Indicates the start of the billing period. - `charge_period_end: datetime` Indicates the end of the charge period. - `charge_period_start: datetime` Indicates the start of the charge period. - `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 cumulated pricing quantity for the billing period. - `pricing_quantity: int` Specifies the pricing quantity for this charge period. - `service_name: str` Identifies the Cloudflare 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. ### Usage Get Response - `List[UsageGetResponseItem]` Contains the array of cost and usage records. - `billing_account_id: str` Public identifier of the Cloudflare account (account tag). - `billing_account_name: str` Display name of the Cloudflare account. - `charge_category: Literal["Usage"]` Highest-level classification of a charge based on the nature of how it gets billed. Currently only "Usage" is supported. - `"Usage"` - `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. - `"Usage-Based"` - `charge_period_end: datetime` Exclusive end of the time interval during which the usage was consumed. - `charge_period_start: datetime` Inclusive start of the time interval during which the usage was consumed. - `consumed_quantity: float` Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations. - `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_name: str` The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter. - `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_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. - `billing_period_start: Optional[datetime]` Inclusive start of the billing cycle that contains this usage record. - `charge_class: Optional[Literal["Correction"]]` Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period. - `"Correction"` - `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. - `x_billable_metric_id: Optional[str]` The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId. - `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). Cloudflare extension. - `x_zone_name: Optional[str]` The display name of the Cloudflare zone. Cloudflare extension.