Discovery

The Discovery API is the read-only "what does this tenant support, and what can be sold here?" surface. Three endpoints answer three questions:

• GET /capabilities — which payment methods, currencies, and gateway integrations is the merchant set up for?

• GET /catalog — which products and payment pages are live, with their lifecycle rules and pricing indicators?

• GET /manifest — what is the full set of v1 operations available to the calling API key?

These endpoints are designed for client bootstrapping: a storefront, mobile app, or partner portal calls them once on load to render the right buttons, currency pickers, and CTA copy without having to encode tenant-specific assumptions.

All three require the read scope. Responses are deterministic per tenant + API key and are safe to cache for the duration of the session.

Endpoints

GET /api/v1/capabilities

Discover merchant capabilities including payment methods and supported currencies

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/capabilities

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Responses

200

Merchant capabilities

No content

get/capabilities

HTTPcURLJavaScriptPython

GET /api/v1/capabilities HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Merchant capabilities

No content

Returns the merchant capability set: enabled paymentMethods (card, ach, sepa, paypal, …), supported currencies, and the active billing-adapter integration metadata (provider name, whether it supports refunds, whether it supports off-session charges). Use it to drive the payment-page UI without hardcoding "we support card and ACH".

Requires the read scope.

GET /api/v1/catalog

List catalog products enriched with lifecycle rules and pricing indicators, plus payment pages

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/catalog

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Responses

200

Enriched catalog with products and payment pages

application/json

paymentPagesobject[]Optional

Payment page summaries

get/catalog

HTTPcURLJavaScriptPython

GET /api/v1/catalog HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Enriched catalog with products and payment pages

{
  "products": [
    {
      "id": "text",
      "name": "text",
      "sku": "text",
      "description": "text",
      "category": "text",
      "productType": "text",
      "priceCents": 1,
      "currency": "text",
      "billingInterval": "text",
      "isActive": true,
      "lifecycleRules": {
        "upgrade": {},
        "downgrade": {},
        "cancellation": {},
        "addOn": {}
      },
      "pricingRules": {
        "hasDynamicPricing": true,
        "pricingTierCount": 1
      }
    }
  ],
  "paymentPages": [
    {}
  ]
}

Returns the live catalog: every active product enriched with the lifecycle rules that govern it (cancellation rule, plan-change rule, applicable add-ons), pricing indicators (hasVariablePricing, hasTieredPricing), and the list of payment pages (CMS slugs) that can sell them.

This is the right call to power a storefront or pricing page; for transactional reads (resolve a single price), use GET /pricing/resolve. For catalog editing the admin surface, use the internal catalog routes, not this endpoint.

Requires the read scope.

GET /api/v1/manifest

Get tenant-level capability manifest describing all available operations

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/manifest

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Responses

200

Tenant capability manifest

application/json

operationsobject[]Optional

paymentPagesobject[]Optional

capabilitiesobjectOptional

get/manifest

HTTPcURLJavaScriptPython

GET /api/v1/manifest HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Tenant capability manifest

{
  "operations": [
    {}
  ],
  "paymentPages": [
    {}
  ],
  "capabilities": {}
}

Returns the full v1 operation manifest as it would apply to the calling API key — operation id, HTTP method + path, the scope it requires, and whether it is currently enabled for this tenant (some operations are gated by the active billing adapter or by a feature flag).

Useful for SDK / CLI clients that need to discover the supported surface dynamically rather than ship a baked-in OpenAPI spec.

Requires the read scope.

Rate limiting (Phase 1a — shadow mode). Every /api/v1/* request is observed by the per-tenant governance middleware (mounted after API-key authentication). Phase 1a is shadow-only: no 429 responses are returned, and rate-limit / concurrency response headers are off by default. Aggregate counts are available to platform admins at GET /api/admin/governance/stats.