.well-known Discovery File

Publishing /.well-known/commerce-gateway.json on your domain makes your gateway discoverable by any resolver implementing the Commerce Gateway Protocol — without requiring registry registration.

Important: The spec explicitly treats well-known discovery as lower trust than verified registry registration. If you want your gateway to appear as verified in registry resolution responses, complete full registration and domain verification in addition to publishing this file.

File location

https://{your-domain}/.well-known/commerce-gateway.json

Must be served over HTTPS. Must return HTTP 200 with Content-Type: application/json.

Schema

{
  "version": "1.0",
  "brand": "Your Brand Name",
  "endpoint": "https://api.your-domain.com",
  "capabilities": [
    "product.search",
    "product.detail",
    "cart.add",
    "order.status"
  ],
  "auth": {
    "type": "bearer",
    "tokenUrl": "https://api.your-domain.com/auth/token"
  },
  "gtinPrefixes": ["0614141"],
  "categories": ["apparel", "footwear"],
  "contact": "commerce-gateway@your-domain.com"
}

Required fields

| Field | Type | Description | | --- | --- | --- | | version | string | Protocol version. Use "1.0" | | brand | string | Human-readable brand name | | endpoint | string | Public HTTPS URL of your gateway | | capabilities | string[] | Tool operations your gateway supports |

Optional fields

| Field | Type | Description | | --- | --- | --- | | auth | object | Auth method and token URL | | gtinPrefixes | string[] | GS1 company prefixes for product lines | | categories | string[] | Commerce categories (apparel, electronics, etc.) | | contact | string | Contact email for gateway operators |

Trust level

Resolvers that implement the protocol distinguish between:

• Well-known only — gateway is discoverable but marked unverified. No domain control proof has been established.
• Registry verified — gateway completed registration and domain verification. Marked active and verified in resolution responses.

Publishing .well-known/commerce-gateway.json is a good first step and enables immediate discoverability. For production use, complete registry registration to move from unverified to verified status.

→ Register and verify your gateway
→ Full .well-known spec