# OpenMerchant

> OpenMerchant makes it easy for merchants to sell products and services to AI agents by importing their existing website, generating agentic-commerce endpoints, and publishing those endpoints on the merchant's behalf.

A merchant gives OpenMerchant its existing website or catalog. OpenMerchant imports the products, services, variants, prices, and availability; converts that catalog into the endpoints and registry entries used by agentic-commerce protocols; and keeps the published data current. This makes the merchant's offers discoverable by agents and assistants such as ChatGPT, Claude, and Gemini.

OpenMerchant currently converts and publishes catalogs for UCP and Google Merchant Center and registers merchant services for MPP. Support for x402 is coming soon.

Merchants can keep their existing storefront and payment processor. Merchants without a store or processor can use OpenMerchant's managed option for the hosted catalog, agentic endpoints, checkout, and payment processing.

OpenMerchant is operated by OpenMerchant Inc. Its dynamic aggregate catalog includes OpenMerchant-MoR and merchant-MoR/BYO sellers. Use the advertised UCP capabilities and service bindings instead of assuming that every listed product can currently be purchased.

- `https://openmerchant.dev/.well-known/ucp` is the live aggregate business profile for sellers represented by OpenMerchant. Live is the default production mode.
- `https://sandbox.openmerchant.dev/.well-known/ucp` is the test aggregate business profile. It advertises `https://api.sandbox.openmerchant.dev/ucp`, so all follow-on catalog and commerce requests remain in test mode.
- `https://api.openmerchant.dev/ucp/openapi.json` is the exact live aggregate UCP implementation contract. The standard UCP `schema` link remains canonical; follow `dev.openmerchant.api_reference` in the business profile for OpenMerchant extensions and deployed operation shapes.
- `https://api.openmerchant.dev/.well-known/ucp` is OpenMerchant's buyer/platform profile. It identifies the agent-side transports, schemas, capabilities, webhook receiver, and payment issuer support; it is not a seller catalog.
- `https://openmerchant.dev/.well-known/openmerchant-environments` is the cross-protocol live/test index. It links the native UCP profiles plus the canonical live and sandbox MPP origins; live is the default.
- `https://openmerchant.dev/.well-known/mpp.json` is OpenMerchant's dynamic compatibility manifest for its shared MPP service. Follow its `docs.apiReference` link to the canonical MPP OpenAPI document; the runtime HTTP 402 response is authoritative for a concrete request.
- Catalog search and lookup can remain available while checkout is disabled. Treat product `availability` and OpenMerchant metadata `purchasable` as independent signals.
- Profiles and catalog responses are generated dynamically. Fetch the current profile and follow its advertised endpoint, capabilities, schemas, signing keys, and payment handlers.
- A checkout must contain products from exactly one seller. Product and variant metadata identify the concrete merchant and link to that merchant's canonical UCP profile.
- On shared hosting, live merchant profiles use `/ucp/{slug}/.well-known/ucp`; test profiles use `/ucp/{slug}/test/.well-known/ucp`. Follow the metadata link instead of deriving or changing its mode path.
- Aggregate mode is selected by origin, not a query parameter, request body, or signing-key convention. Standard origins are live and `sandbox` origins are test; staging mirrors both at `https://staging.openmerchant.dev` and `https://sandbox.staging.openmerchant.dev`.

## MPP 401 and 402 recovery

MPP customer identity and payment are sequential challenges. Keep the purchase body and idempotency key unchanged across retries so the seller can preserve the customer binding and order state.

1. A purchase that returns HTTP `401` with `detail.error_code` set to `identity_required` requires customer OAuth before payment. Read `detail.message`, `detail.authorization_server`, `detail.authorization_endpoint`, `detail.token_endpoint`, and `detail.resource_metadata`; the structured fields are authoritative.
2. Open `detail.authorization_endpoint` in the customer's browser using OAuth Authorization Code with PKCE. The registered buyer client supplies `client_id` and its exact `redirect_uri`, generates and validates a fresh `state`, generates a fresh `code_verifier`, and sends its derived S256 `code_challenge`. Request the checkout scope advertised by the protected-resource metadata.
3. After the registered callback receives the authorization `code`, POST a form-encoded `authorization_code` grant to `detail.token_endpoint` using the same `redirect_uri`, the retained `code_verifier`, and the buyer client's registered token-endpoint authentication method. Store the returned access and refresh tokens securely.
4. Retry the identical purchase with `Authorization: Bearer <access_token>`. A valid customer token advances the same purchase to HTTP `402`; it does not complete payment.
5. For HTTP `402`, parse the runtime `WWW-Authenticate: Payment …` challenge and the JSON payment requirements. Obtain the challenge's requested payment credential through its named payment network or handler. For Stripe Shared Payment Tokens, follow the advertised Stripe SPT handler and bind the credential to the challenged seller, amount, currency, and mode.
6. Retry the identical purchase and idempotency key with the challenge-built `Authorization: Payment …` value. Do not include the earlier Bearer value on this paid retry: the pending order already carries the verified customer binding. On success, consume the `Payment-Receipt` response header and order JSON.

An anonymous public MPP request cannot receive a complete OAuth authorization URL because it does not identify the buyer platform's registered `client_id` or callback and cannot safely choose the caller's `state` or PKCE secret. OpenMerchant's authenticated profile-link flow can return a complete `authorize_url` because it knows the registered first-party client and manages state, PKCE, callback exchange, token storage, and refresh on the profile's behalf.

## Agent commerce

- [Buyer integration guide](https://openmerchant.dev/developers): Build a buying agent with catalog discovery, sandbox mode, customer OAuth, and payments.
- [Readable API reference and integration guides](https://api.openmerchant.dev/api_reference?view=readable): Complete public operation reference and buyer/merchant guides as HTML without JavaScript.

- [Live aggregate UCP business profile](https://openmerchant.dev/.well-known/ucp): Discover the current live seller capabilities, REST service binding, signing key, and payment handlers.
- [Test aggregate UCP business profile](https://sandbox.openmerchant.dev/.well-known/ucp): Discover the isolated sandbox catalog and its test REST service binding.
- [Aggregate UCP OpenAPI](https://api.openmerchant.dev/ucp/openapi.json): Inspect the exact live request and response shapes implemented by OpenMerchant's aggregate UCP binding.
- [OpenMerchant buyer/platform UCP profile](https://api.openmerchant.dev/.well-known/ucp): Discover the transports and schemas OpenMerchant understands when acting as a buyer platform.
- [OpenMerchant environment index](https://openmerchant.dev/.well-known/openmerchant-environments): Discover the live and test UCP and MPP entry points and their mode-selection rules.
- [OpenMerchant MPP service manifest](https://openmerchant.dev/.well-known/mpp.json): Discover the shared service origin, merchant-slug endpoint templates, supported payment methods, and canonical MPP OpenAPI reference.
- [OpenMerchant UCP quote specification](https://openmerchant.dev/ucp/2026-04-08/specification/quotes.md): Request synchronous merchant-authoritative quantity or booking offers with reconciled tax and fulfillment totals, then purchase a selected offer without checkout repricing.
- [OpenMerchant UCP quote schema](https://openmerchant.dev/ucp/2026-04-08/schemas/quotes.json): Machine-readable request and response shapes advertised for `dev.openmerchant.quotes`.
- [Public OpenAPI schema](https://openmerchant.dev/v1/openapi.json): Machine-readable public API contract for OpenMerchant endpoints.
- [Stripe SPT handler schema](https://api.openmerchant.dev/ucp/payment_handlers/stripe_spt.schema.json): Context-specific business, platform, and runtime response schemas for Stripe Shared Payment Token negotiation.

## Product

- [OpenMerchant](https://openmerchant.dev/): Product overview, supported agentic-commerce protocols, FAQs, and merchant onboarding.
- [Request early access](https://openmerchant.dev/#waitlist): Join the founding-merchant onboarding waitlist.

## Policies

- [Terms of service](https://openmerchant.dev/terms): Draft terms pending counsel review.
- [Privacy policy](https://openmerchant.dev/privacy): Draft privacy policy pending counsel review.
- [Refund policy](https://openmerchant.dev/refunds): Draft refund policy pending counsel review.

## Optional

- [Universal Commerce Protocol](https://ucp.dev/): External UCP specification and schemas.
- [Machine Payments Protocol services](https://mpp.dev/services): External MPP service registry.