Deploy payment ruleset

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

Path ParametersExpand Collapse

zone_id: string

The unique ID of the zone.

Body ParametersJSONExpand Collapse

rules: array of MonetizationRuleInput

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:

MonetizationRuleInputFixedPrice object { address, expression, price, 4 more }

Payment rule with a fixed price set at configuration time.

address: string

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: string

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

price: string

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: "exact" or "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 string

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 string

maxLength512

enabled: optional boolean

MonetizationRuleInputOriginControlled object { address, expression, scheme, 3 more }

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: string

expression: string

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

scheme: "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 string

maxLength32

description: optional string

maxLength512

enabled: optional boolean

ReturnsExpand Collapse

errors: array of object { code, message }

code: optional number

message: optional string

messages: array of object { code, message }

code: optional number

message: optional string

result: MonetizationRuleCollection { rules }

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: array of MonetizationRule

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

One of the following:

MonetizationRulesMonetizationRuleInputFixedPrice = MonetizationRuleInputFixedPrice { address, expression, price, 4 more }

Payment rule with a fixed price set at configuration time.

id: string

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

maxLength32

MonetizationRulesMonetizationRuleInputOriginControlled = MonetizationRuleInputOriginControlled { address, expression, scheme, 3 more }

id: string

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

maxLength32

success: true

Deploy payment ruleset

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/monetization/rules \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "rules": [
            {
              "address": "0x1234567890abcdef1234567890abcdef12345678===",
              "expression": "(http.request.uri.path eq \\"/premium\\" and http.request.method in {\\"GET\\" \\"POST\\"})",
              "price": "250000",
              "scheme": "exact"
            }
          ]
        }'

{
  "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
}