Pricing

The Pricing API evaluates the tenant's pricing-rule engine for a given product + buyer context and returns the resolved unit price along with a transparent breakdown of which rules fired. It is the single source of truth for "what should we charge this customer right now"; checkout flows, quoting tools, and the Preview endpoints all defer to it.

The engine combines:

• catalog list price (from the product's plan / charge),

• targeting rules in pricing_rules (segment / locale / partner / quantity / journey),

• tier tables for volume pricing,

• partner-specific overrides via partner_rules.

Reads require the read scope. The endpoint is read-only and side-effect free; safe to call from a browser.

Endpoints

GET /api/v1/pricing/resolve

Resolve the effective price for a product given customer context (segment, locale, partner, quantity). Returns the resolved price with a breakdown of pricing rules applied.

get

/pricing/resolve

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters

productIdstringRequired

segmentstringOptional

localestringOptional

partnerstringOptional

quantityintegerOptionalDefault: 1

Responses

200

Resolved pricing

application/json

Resolved effective price after applying pricing tiers, quantity, and offer discounts

productIdstringOptional

productNamestringOptional

basePriceCentsintegerOptional

Price before offer discounts

resolvedPriceCentsintegerOptional

Final price after all rules and discounts

currencystringOptional

quantityintegerOptional

contextobjectOptional

Customer context used for resolution

availableOffersobject[]Optional

404

Product not found

get/pricing/resolve

GET /api/v1/pricing/resolve?productId=text HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "productId": "text",
  "productName": "text",
  "basePriceCents": 1,
  "resolvedPriceCents": 1,
  "currency": "text",
  "quantity": 1,
  "context": {},
  "rulesApplied": [
    {
      "rule": "text",
      "type": "text",
      "adjustment": "text",
      "detail": "text"
    }
  ],
  "availableOffers": [
    {}
  ]
}

Resolves the effective unit price for productId given the supplied buyer context. Pass any subset of the optional discriminators — segment, locale, partner, quantity — and the engine narrows the rule set accordingly.

The response includes:

• price — the resolved unit price in cents.

• currency — the currency the price is denominated in (driven by the locale match, falling back to the product default).

• breakdown — an ordered list of { ruleId, ruleType, adjustment } entries showing which pricing_rules rows fired and what each contributed.

• tier (when applicable) — the matched row from the rule's tier_table for volume pricing.

Returns 404 when the product is not found in the tenant's catalog. Cache aggressively client-side: the response is deterministic for a given (productId, segment, locale, partner, quantity) tuple until the tenant edits a rule.

Requires the read scope.