Deploy payment ruleset

monetization.rules.update() -> MonetizationRuleCollection

PUT/zones/{zone_id}/monetization/rules

Replaces the zone’s Payment Required ruleset with the submitted desired state. Submit an empty rules array to clear all payment rules.

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

zone_id: str

The unique ID of the zone.

rules: Iterable[MonetizationRuleInputParam]

Full desired Payment Required ruleset. An empty array clears all payment rules. The ruleset may contain at most 40 unique wallet addresses; address comparison is case-insensitive. Every address must pass wallet screening before deployment.

One of the following:

class MonetizationRuleInputFixedPrice: …

Payment rule with a fixed price set at configuration time.

address: str

0x-prefixed 20-byte hexadecimal Ethereum address. Mixed-case addresses must carry a valid EIP-55 checksum; all-lowercase or all-uppercase addresses are also accepted. The address must pass wallet screening whenever its rule is deployed or patched.

expression: str

Wirefilter expression identifying the requests that require payment. Forwarded verbatim to the Rulesets API, which validates its syntax.

price: str

Price in the smallest indivisible unit of the configured payment token, encoded as a decimal string. Must be a canonical decimal integer in [1000, 100000000]: no leading zeros, and a bare JSON number is rejected. The price is required for the fixed-price schemes (“exact” and “upto”) and must be at least 1000, the smallest amount the payment facilitator can settle ($0.001 for a 6-decimal token such as USDC), and at most 100000000 ($100 for a 6-decimal token). When the scheme is “origin_controlled” the origin server sets pricing dynamically and the rule carries no price: the field must be omitted — any provided value, including “0”, is rejected because it would not be enforced. Responses always encode this as a string and omit it for “origin_controlled” rules; the pattern matches exactly the set of values the server accepts.

scheme: Literal["exact", "upto"]

X402 payment scheme. “exact” requires the specified payment amount; “upto” permits a payment up to the specified amount. Both fixed-price schemes require the price field.

One of the following:

"exact"

"upto"

id: Optional[str]

Optional on input. Include the ID of an existing payment rule to update it in place, preserving its stable identity across the full-ruleset replacement; omit it to create a new rule. An ID that does not match an existing payment rule in the zone is rejected. Rules omitted from the request are deleted.

maxLength32

description: Optional[str]

maxLength512

enabled: Optional[bool]

class MonetizationRuleInputOriginControlled: …

Payment rule whose price the origin server sets dynamically. The rule carries no price and the price field must be omitted — any provided value, including “0”, is rejected because it would not be enforced.

address: str

expression: str

Wirefilter expression identifying the requests that require payment. Forwarded verbatim to the Rulesets API, which validates its syntax.

scheme: Literal["origin_controlled"]

X402 payment scheme. “origin_controlled” lets the origin server set pricing dynamically; the rule carries no price and the price field must be omitted.

id: Optional[str]

maxLength32

description: Optional[str]

maxLength512

enabled: Optional[bool]

ReturnsExpand Collapse

class MonetizationRuleCollection: …

The zone’s payment rules. Mirrors the shape of the ruleset submitted to the deploy endpoint, so the response can be read back as the desired state.

rules: List[MonetizationRule]

The zone’s payment rules, in the order they are evaluated. Empty when the zone has no payment rules.

One of the following:

class MonetizationRulesMonetizationRuleInputFixedPrice: …

Payment rule with a fixed price set at configuration time.

id: str

The server-assigned unique ID of the payment rule. Stable across full-ruleset replacements.

maxLength32

class MonetizationRulesMonetizationRuleInputOriginControlled: …

id: str

The server-assigned unique ID of the payment rule. Stable across full-ruleset replacements.

maxLength32

Deploy payment ruleset

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
monetization_rule_collection = client.monetization.rules.update(
    zone_id="9f1839b6152d298aca64c4e906b6d074",
    rules=[{
        "address": "0x1234567890abcdef1234567890abcdef12345678===",
        "expression": "(http.request.uri.path eq \"/premium\" and http.request.method in {\"GET\" \"POST\"})",
        "price": "250000",
        "scheme": "exact",
    }],
)
print(monetization_rule_collection.rules)

{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "rules": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678===",
        "expression": "(http.request.uri.path eq \"/premium\" and http.request.method in {\"GET\" \"POST\"})",
        "price": "250000",
        "scheme": "exact",
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "description": "Premium API endpoint",
        "enabled": true
      }
    ]
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "rules": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678===",
        "expression": "(http.request.uri.path eq \"/premium\" and http.request.method in {\"GET\" \"POST\"})",
        "price": "250000",
        "scheme": "exact",
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "description": "Premium API endpoint",
        "enabled": true
      }
    ]
  },
  "success": true
}