PATTERN Cited by 1 source

Price Header Negotiation¶

Price Header Negotiation is the HTTP-level design pattern for per-request paid-content access: a seller expresses a price in a response header (or acknowledges one in response to a client header), a buyer expresses willingness to pay in a request header, and the HTTP 402 Payment Required status code is the signaling primitive that ties the two sides together. Cloudflare's 2025-07-01 pay-per-crawl is the canonical wiki instance.

Two flows¶

Reactive — discovery first¶

Client requests without declaring payment intent:
```
GET /example.html
```

Server replies with price:

HTTP/1.1 402 Payment Required
crawler-price: USD 0.01

Client decides to pay, retries with agreement header:
```
GET /example.html
crawler-exact-price: USD 0.01
```
Server serves content with charge confirmation:
```
HTTP/1.1 200 OK
crawler-charged: USD 0.01
```

Cost: two round-trips per priced resource when price is unknown. Fits discovery-time / spidering workflows that want to see the price before committing.

Preemptive — ceiling-declared up front¶

Client declares its spending ceiling on the first request:
```
GET /example.html
crawler-max-price: USD 0.02
```
If configured price ≤ ceiling, server serves content and charges the configured price (not the ceiling):
```
HTTP/1.1 200 OK
crawler-charged: USD 0.01
```
If configured price > ceiling, server replies 402 Payment Required with the actual crawler-price for the client to decide whether to retry.

Cost: one round-trip in the common case (price within budget). Preferred for pipeline / streaming / latency-sensitive agent work.

Design properties¶

Buyer declares intent, seller declares amount. Request headers never say the buyer's actual maximum unless preemptive; response headers always carry the seller's configured price. Symmetrical role separation — buyer can abandon, seller can't overcharge past its own configured price.
Exclusive-or on payment headers. Only one of crawler-exact-price / crawler-max-price is allowed per request. Prevents contradictory intents.
Confirmed amount echoes back in crawler-charged — buyer's reconciliation / audit trail pulls from the response, not the request it sent.
402 does not mean "this bot is blocked" — it means "this priced resource is available for the quoted amount". A flat block would be 403. Pay-per-crawl's architecture uses 402 even for "charge a non-billing-relationship crawler" cases so the crawler learns the offer terms.

Generalizes beyond Cloudflare¶

The price / exact-price / max-price / charged header shape is not IETF-standardized at pay-per-crawl's 2025-07-01 launch — it's a de-facto Cloudflare convention. The pattern, though — 402-gated, header-driven price + agreement + confirmation — is likely to become the substrate for any agentic-paywall deployment. Potential future generalizations include per-path price variation, dynamic demand-based prices, and per-use-class licenses (training vs inference vs search) — all of which fit the same header-exchange shape with additional headers.

Seen in¶

sources/2025-07-01-cloudflare-pay-per-crawl — pay-per-crawl reactive + preemptive flows; canonical wiki instance.

concepts/http-402-payment-required — the signaling primitive.
systems/pay-per-crawl — the canonical implementing system.
concepts/agentic-paywall — the use case motivating the pattern's generalization.