Open Storefront Protocol Specification

OSP enables any AI agent - whether it's ChatGPT, Claude, Gemini, or a custom shopping assistant - to query products, negotiate prices, and complete purchases from any OSP-compatible storefront using a single, consistent protocol.

• Simplicity: RESTful JSON APIs that any developer can implement in hours
• Machine-readability: Every response is structured for AI consumption, not human browsing
• Extensibility: Custom attributes and metadata without breaking the protocol
• Backward compatibility: New features never break existing integrations within a major version

OSP uses semantic versioning. The current version is 3.0. Minor versions (3.1, 3.2) add features without breaking changes. Major versions may introduce breaking changes with a 6-month deprecation window. A withdrawal for a correctness or safety defect is immediate and does not use that window, as POST /transactions was on 2026-09-10.

OSP follows a three-tier architecture:

1. Agent sends an authenticated request to the storefront API endpoint
2. The storefront validates the API key, rate limits, and request schema
3. The request is processed against the brand's catalog and policies
4. A structured JSON response is returned with product data, negotiation state, or transaction status
5. The agent parses the response and presents results to the user

https://cresva.ai/api/storefront/{brandId}

All endpoints are relative to this base URL. Replace {brandId}with the brand's unique identifier.

The two hosts are not interchangeable. api.cresva.ai serves the platform API at /v1/ and the .well-known documents, and answers every other path with a 404 before routing. A storefront path sent there returns not_found whatever else is right about it.

All requests and responses use application/json. Requests must include the Content-Type: application/json header for POST/PUT/PATCH methods.

Cresva never holds, receives, routes, finances, insures, or pays out funds. OSP facilitates discovery, negotiation, and order handoff between an agent and a storefront; payment happens directly between the buyer and the merchant, on the merchant's own rails. See Section 6, Transactions, for how this applies to the transaction lifecycle specifically.

A storefront is described by a JSON document at /.well-known/osp.json. On a multi-tenant host it is addressed by brand, and the bare path describes the platform rather than a shop:

GET https://{domain}/.well-known/osp.json

The discovery file format:

{
  "osp_version": "3.0",
  "storefront_url": "https://cresva.ai/api/storefront/brand_abc123",
  "brand_id": "brand_abc123",
  "brand_name": "Acme Co",
  "capabilities": [
    "search",
    "recommend",
    "compare",
    "negotiate",
    "transact"
  ],
  "supported_currencies": ["USD", "EUR"],
  "supported_languages": ["en", "es", "fr"],
  "rate_limits": {
    "public": "60/minute",
    "authenticated": "300/minute",
    "anonymous": "10/minute"
  },
  "documentation": "https://developers.cresva.ai/protocol/spec"
}

The request body for a query:

Inside query: filters takes category, price_min, price_max, currency, attributes, in_stock and rating_min, as separate fields rather than a nested range object. context takes user_budget, user_preferences, previous_products_viewed and comparison_against.

// No credential. x-cresva-auth for this operation is "none".
POST /api/storefront/{brandId}/query
Content-Type: application/json

{
  "query": {
    "text": "snowboard",
    "intent": "search",
    "filters": { "in_stock": true, "price_max": 900, "currency": "USD" },
    "context": { "user_preferences": ["all-mountain"] }
  },
  "agent": { "platform": "audit" },
  "pagination": { "limit": 2 }
}

• Volume discount: Better price for buying multiple units
• Bundle: Discount when purchasing with related products
• Subscription: Lower per-unit price for recurring purchases
• Time-limited: Special price valid for a limited window

Negotiations expire after 24 hours of inactivity. Brands can configure shorter timeouts. That figure is the intended behaviour and is not sourced to a published constant, so do not build a timer against it. The expires_at field in the response indicates when the current offer expires.

A transaction MAY carry an optional confirmation window: a status-only period after payment during which the buyer can confirm receipt early, or raise a dispute, before the window auto-closes on its own due date. STATUS ONLY: no funds move through Cresva at any point, at any status value. This is a release-timing state machine on a record, not fund custody. The confirmation window's status is one of pending_confirmation, confirmed, or disputed, and starts at pending_confirmation only when the storefront explicitly enables it on transaction creation.

Cresva never holds funds. Payment happens directly between the buyer and the merchant, on the merchant's own payment rails, exactly as it would on the merchant's own storefront. OSP is not a party to the transaction, does not process the payment, and holds no funds at any point in this flow. Where a payment reference is useful, the storefront may include an external id from its own payment provider on the transaction record; OSP stores it as-is without acting on it.

// Request. Needs a secret key.
POST /api/storefront/{brandId}/checkout/sessions
{
  "items": [
    { "product_id": "cmtpqwhge000wjv049l5iij9q", "quantity": 1 }
  ]
}

// There is no price field, and that is the point. A line is priced
// from the catalogue at the moment it is added, never from this body.

// Completing the session returns a link the buyer opens to pay
// the merchant. Cresva takes nothing and holds nothing.
POST /api/storefront/{brandId}/checkout/sessions/{sessionId}/complete

POST /transactions is withdrawn and answers 410 Gone. See the transactions reference for the refusal body and what replaced it.

Agents SHOULD use trust scores to weight recommendations. Higher-trust storefronts should be preferred when product quality and price are comparable. Agents MUST NOT hide products solely based on trust score but MAY include trust information in recommendations to users.

Deliveries are signed with HMAC-SHA256 over the raw request body and carry X-Cresva-Signature with a sha256= prefix. See the webhooks guide for verification code in three languages.

Failed webhook deliveries (non-2xx response, or timeout after 10 seconds) are retried with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 12 hours. After 5 failed attempts the endpoint is marked failed and stops receiving deliveries. No email is sent.

Authorization: Bearer pk_live_your_key_here

Include the API key in the Authorization header of every request using the Bearer scheme.

Rate limits are applied per API key, per IP for anonymous callers, and per brand across all callers. When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when the limit resets.

Every request and response includes an X-OSP-Version header, with X-ACP-Version sent alongside it carrying the identical value for clients written before the rename. Clients SHOULD send their supported version; servers MUST include the version used to process the request.

This header is a dated wire revision, not the spec version. The body's osp_version is a semver and states which version of this specification a storefront implements. The header states which wire contract is in use and is a date. They are different facts and are not expected to match.

// Request
X-OSP-Version: 2026-03-01

// Response
X-OSP-Version: 2026-03-01
X-ACP-Version: 2026-03-01

• New optional fields MAY be added to responses without a version bump
• New optional request fields MAY be added without a version bump
• Existing fields MUST NOT be removed or have their type changed within a major version
• New required fields MUST trigger a major version increment
• New endpoints MAY be added in minor versions

When a feature or endpoint is deprecated:

1. A deprecation notice is published in the changelog. No Sunset header is sent today, and this document does not promise one until it is.
2. The feature continues to work for 6 months after the deprecation notice
3. After the sunset date, the endpoint returns 410 Gone

See the full protocol changelog for a detailed history of all versions and changes.