Fields Reference
Core Fields (v1)
The following table lists all fields defined in version 1. Fields marked REQUIRED must be present for the file to be considered valid.
| Field | Required | Repeatable | Description |
|---|---|---|---|
| Version | Yes | No | Specification version |
| Contact | Yes | Yes | How to reach a human |
| Commerce-Protocol | No | Yes | Agentic commerce protocol(s) supported |
| Interaction-Model | No | No | Expected level of human involvement in procurement |
| Pricing | No | No | How pricing information is available |
| Ordering | No | No | How to place an order |
| Negotiation | No | No | Whether negotiation is supported |
| Service-Region | No | No | Geographic regions the merchant serves |
| Min-Order | No | No | Minimum order value or quantity |
| Payment-Terms | No | No | Accepted payment methods and terms |
| Auth | No | No | Authentication required for merchant APIs |
| Rate-Limit | No | No | Request rate guidance for agents |
| Quote | No | No | How automated quoting is accessed |
| Invoice | No | No | How automated invoicing is accessed |
| Tracking | No | No | How order tracking is accessed |
| Returns | No | No | How automated returns are accessed |
| Subscription | No | No | How recurring orders are accessed |
| Rfq | No | No | How request-for-quote workflows are accessed |
| Escalation | No | Yes | URI for human escalation |
| Catalog | No | No | URI to a product catalog or feed |
| Expires | No | No | When this file should be re-fetched |
| Preferred-Languages | No | No | Languages the merchant supports |
| Canonical-Hash | No | No | Integrity hash for tamper detection |
Field Definitions
Version
Description: The version of the procurement.txt specification the file conforms to.
Allowed values: A positive integer.
Required: Yes.
Version: 1
Contact
Description: A URI or email address for reaching a human about procurement. This field MAY be repeated to provide multiple contact methods.
Allowed values: A mailto: URI, an https: URI, or a tel: URI.
Required: Yes. Repeatable: Yes.
Contact: mailto:sales@example.com
Contact: https://example.com/contact
Contact: tel:+1-555-867-5309
Commerce-Protocol
Description: Declares support for an agentic commerce protocol. This field MAY be repeated to declare support for multiple protocols. Each value names the protocol and provides the endpoint URI at which the merchant supports it.
When a Commerce-Protocol field is present, Ordering: protocol MAY be used to indicate that ordering is handled entirely through the declared protocol (including payment, where the protocol supports it).
Allowed values: A protocol name keyword followed by a space and an https: URI pointing to the merchant's protocol endpoint.
| Protocol name | Protocol | Notes |
|---|---|---|
ucp | Universal Commerce Protocol | Created by Google; supported by Shopify and others |
acp | Agentic Commerce Protocol | Supported by OpenAI and others |
Protocol names are extensible. Agents MUST ignore unrecognized protocol names without treating the field as invalid.
Required: No. Repeatable: Yes.
Commerce-Protocol: ucp https://shop.example.com/ucp
Commerce-Protocol: acp https://api.example.com/acp/v1
Interaction-Model
Description: Declares the expected level of human involvement in procurement. This helps agents determine upfront whether they can complete a transaction autonomously or must involve a human at some stage.
Allowed values:
| Keyword | Meaning |
|---|---|
automated | Fully automated; no human approval required for standard transactions. Typical for consumer retail and one-shot purchases. |
approval-required | An agent may discover, quote, and prepare an order, but a human must authorize the final commitment. Typical for regulated or high-value B2B procurement. |
human-led | Primarily human-driven; an agent may assist with discovery and preparation but all transactions are initiated or confirmed by a human. |
hybrid | Some transactions are automated (typically below a value threshold) and others require human approval. Use X-Auto-Approve-Under to express a threshold. |
If this field is absent, agents MUST NOT assume any particular level of automation — the interaction model is unknown.
Required: No. Repeatable: No.
Interaction-Model: automated
Interaction-Model: approval-required
Interaction-Model: hybrid
X-Auto-Approve-Under: 500 USD
Pricing
Description: Declares how pricing information can be obtained.
Allowed values: One of the following keywords, optionally followed by a space and a URI.
| Keyword | Meaning |
|---|---|
public | Prices are listed on the website |
on-request | Prices are available on request (use Contact) |
api | Prices are available via an API (URI must follow) |
catalog | Prices are in the referenced Catalog |
When api is used, the URI MUST point to a machine-readable API specification (OpenAPI 3.x strongly recommended) or structured API documentation. The URI MUST NOT be a raw endpoint. An agent resolving this URI must be able to determine the full request structure from the document alone.
Pricing: public
Pricing: api https://api.example.com/openapi.json
Pricing: on-request
Ordering
Description: Declares how orders can be placed.
Allowed values: One of the following keywords, optionally followed by a space and a URI.
| Keyword | Meaning |
|---|---|
website | Orders are placed through the merchant's website |
email | Orders are placed via email (use Contact) |
api | Orders are placed through an API (URI must follow) |
phone | Orders are placed by phone (use Contact) |
protocol | Ordering is handled through a declared Commerce-Protocol endpoint |
When api is used, the URI MUST point to a machine-readable API specification (OpenAPI 3.x strongly recommended) or structured API documentation. The URI MUST NOT be a raw endpoint. An agent resolving this URI must be able to determine the full request structure — method, path, parameters, payload schema, and response format — from the document alone.
Ordering: website https://example.com/shop
Ordering: api https://api.example.com/openapi.json
Negotiation
Description: Declares whether the merchant supports price or term negotiation.
Allowed values:
| Value | Meaning |
|---|---|
yes | Negotiation is available (initiate via Contact or Escalation) |
no | Prices and terms are fixed |
bulk-only | Negotiation is available only for bulk or volume orders |
Negotiation: bulk-only
Service-Region
Description: Declares the geographic regions the merchant serves — ships to, operates in, or delivers to. Helps agents quickly determine if this merchant is relevant before fetching further details.
Allowed values: A comma-separated list of ISO 3166-1 alpha-2 country codes, or the keyword global.
Required: No. Repeatable: No.
If absent, agents SHOULD NOT assume any particular geographic availability — availability is unknown.
Service-Region: US, CA, MX
Service-Region: global
Min-Order
Description: Declares a minimum order value or quantity. Common in B2B procurement where suppliers require a minimum spend per transaction.
Allowed values: A number followed by a space and an ISO 4217 currency code, or the keyword none.
Required: No. Repeatable: No.
Min-Order: 500 USD
Min-Order: 1000 EUR
Min-Order: none
Payment-Terms
Description: Declares the payment terms the merchant accepts. Critical for B2B procurement where net terms, purchase orders, and trade credit are standard.
Allowed values: A comma-separated list of the following keywords:
| Keyword | Meaning |
|---|---|
prepaid | Payment required before fulfillment |
net-30 | Payment due within 30 days of invoice |
net-60 | Payment due within 60 days of invoice |
net-90 | Payment due within 90 days of invoice |
purchase-order | Purchase orders accepted |
credit-card | Credit card payment accepted |
wire | Wire transfer accepted |
on-account | Existing account or credit terms apply |
Required: No. Repeatable: No.
Payment-Terms: credit-card, wire
Payment-Terms: net-30, net-60, purchase-order, wire
Auth
Description: Declares how agents authenticate with the merchant's APIs. This is a discovery hint — full authentication details remain in the OpenAPI specification referenced by api URI fields. Agents can use this field to determine upfront whether credentials are needed and what kind, before fetching a full API specification.
Allowed values: A comma-separated list of the following keywords:
| Keyword | Meaning |
|---|---|
none | No authentication required |
api-key | API key required (obtain out-of-band) |
oauth2 | OAuth 2.0 flow required |
basic | HTTP Basic Auth |
custom | Custom authentication — see the API specification |
Required: No. Repeatable: No.
Auth: api-key
Auth: oauth2, api-key
Auth: none
Rate-Limit
Description: Advisory rate limit for automated requests to the merchant's purchasing-related pages or APIs. This is guidance, not enforcement.
Allowed values: An integer followed by a slash and a time unit (second, minute, hour).
Rate-Limit: 10/minute
Capability Fields
The following six fields declare individual procurement capabilities. Each follows the same value pattern as Ordering and Pricing, allowing the merchant to express both that a capability exists and how to access it.
Shared allowed values:
| Keyword | Meaning |
|---|---|
yes | Capability exists; initiate via Contact or Escalation |
website <URI> | Use this URL (web form, portal, self-serve page) |
api <URI> | Use the OpenAPI 3.x spec at this URI (see 3.4) |
When api is used, the URI MUST point to a machine-readable API specification — not a raw endpoint. Authentication requirements will be found in the spec's securitySchemes declaration.
Absence of a capability field means that capability has not been declared — it is not the same as "not supported".
Quote
Description: Declares whether and how the merchant can provide automated price quotes.
Quote: yes
Quote: website https://example.com/request-quote
Quote: api https://api.example.com/openapi.json
Invoice
Description: Declares whether and how the merchant can generate invoices.
Invoice: yes
Invoice: website https://example.com/invoices
Invoice: api https://api.example.com/openapi.json
Tracking
Description: Declares whether and how order tracking is available.
Tracking: yes
Tracking: website https://example.com/track
Tracking: api https://api.example.com/openapi.json
Returns
Description: Declares whether and how automated returns or RMA (Return Merchandise Authorization) are supported.
Returns: yes
Returns: website https://example.com/returns
Returns: api https://api.example.com/openapi.json
Subscription
Description: Declares whether and how recurring or scheduled orders are supported.
Subscription: yes
Subscription: website https://example.com/subscriptions
Subscription: api https://api.example.com/openapi.json
Rfq
Description: Declares whether and how request-for-quotation (RFQ) workflows are supported. RFQ is a formal procurement process where a buyer solicits itemized quotes from a supplier before committing to an order.
Rfq: yes
Rfq: website https://example.com/rfq
Rfq: api https://api.example.com/openapi.json
Escalation
Description: A URI where an agent can hand off a transaction to a human. This field MAY be repeated.
Allowed values: A mailto:, https:, or tel: URI.
Repeatable: Yes.
Escalation: https://example.com/live-chat
Escalation: mailto:procurement@example.com
Catalog
Description: A URI pointing to a machine-readable product catalog or feed.
Allowed values: An https: URI. The format of the catalog itself is outside the scope of this specification.
Catalog: https://example.com/products.csv
Expires
Description: A date after which agents SHOULD re-fetch the file. This does not prevent caching before the date; it provides a maximum staleness hint.
Allowed values: An ISO 8601 date or datetime in UTC.
Expires: 2026-12-31
Expires: 2026-12-31T23:59:59Z
Preferred-Languages
Description: A comma-separated list of languages the merchant can conduct procurement in.
Allowed values: IETF BCP 47 language tags.
Preferred-Languages: en, es, fr
Canonical-Hash
Description: A self-referential integrity hash that allows agents to verify the file has not been modified after the merchant published it. Useful when the file is served through a CDN, proxy, or cache layer.
Allowed values: sha256: followed by 64 lowercase hexadecimal characters.
Required: No. Repeatable: No.
This is not a cryptographic signature — it does not prove authorship. It detects post-publication modification (similar to how Subresource Integrity works in browsers). Domain trust via HTTPS remains the primary trust signal.
Computing the hash (merchants):
- Compose the complete file with all intended fields.
- Remove the
Canonical-Hashline (or set its value to empty string). - Normalize line endings to
LF. - Compute SHA-256 of the resulting content.
- Write the hex digest as the value.
Verifying the hash (agents):
- Fetch the file.
- Remove the
Canonical-Hashline. - Normalize line endings to
LF. - Compute SHA-256.
- Compare with the declared hex digest.
Agents SHOULD treat a mismatch as a warning, not a hard failure. The merchant may have updated the file without recomputing the hash.
Canonical-Hash: sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd
Extensibility
Extension Fields (X- prefix)
Merchants and agent developers MAY define custom fields using the X- prefix. Extension field names MUST begin with X- followed by a descriptive name using hyphens as separators.
X-Lead-Time-Days: 5
X-Sustainability-Cert: iso-14001
X-SLA-Response: 4 hours
To avoid collisions between independent extensions, authors of widely-used extensions SHOULD use a longer prefix that includes an organization identifier:
X-Acme-Custom-Field: value
Agents MUST ignore unrecognized fields. Merchants MUST NOT rely on extension fields being understood by any particular agent.