Pricing previews

Preview endpoints are read-only operations that return what would happen if you executed a plan change, add-on attach, or cancellation — including effective date, proration, applicable business rule, plan dependency adjustments, and policy evaluation.

The pricing-resolve endpoint returns the effective price for a product given a customer context.

• POST /api/v1/preview/plan-change

• POST /api/v1/preview/add-on

• POST /api/v1/preview/cancellation

• GET /api/v1/pricing/resolve

---

POST /api/v1/preview/plan-change

Preview a plan change. No state changes.

• Auth scope: read

Body

Field	Type	Required
subscriptionId	UUID	yes
targetProductId	UUID	yes

Response 200

{
  "data": {
    "subscriptionId": "sub_01H...",
    "currentProduct": { "id": "prod_a", "name": "Starter", "priceCents": 1900 },
    "targetProduct":  { "id": "prod_b", "name": "Pro",     "priceCents": 4900 },
    "direction": "upgrade",
    "effectiveDate": "2026-05-02T14:01:23Z",
    "planDependencyAdjustments": [
      {
        "linkId": "ln_01H...",
        "sourceChargeId": "ch_a",
        "targetChargeId": "ch_b",
        "targetField": "quantity",
        "explanation": "Will keep quantity in sync after plan change via \"Base ↔ add-on seats\""
      }
    ],
    "financialImpact": {
      "currentPriceCents": 1900,
      "newPriceCents": 4900,
      "creditCents": 950,
      "chargeCents": 2450,
      "netCents": 1500,
      "currency": "USD"
    },
    "businessRule": {
      "ruleId": "br_01H...",
      "ruleName": "Default upgrade",
      "direction": "upgrade",
      "changeTiming": "immediate",
      "prorationType": "prorated"
    },
    "policyEvaluation": {
      "allowed": true,
      "evaluations": [
        { "policyId": "pol_01H...", "policyName": "...", "policyType": "plan_change", "result": "allow" }
      ]
    },
    "resolvedPrice": {
      "basePriceCents": 4900,
      "pricingTierCount": 3,
      "tiers": [
        { "id": "pt_01H...", "name": "Default", "price": "4900", "currency": "USD", "chargeModel": "flat" }
      ]
    }
  }
}

Errors

Status	When
404	Subscription or target product not found

cURL

curl -X POST https://api.example.com/api/v1/preview/plan-change \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscriptionId": "sub_uuid", "targetProductId": "prod_uuid" }'

---

POST /api/v1/preview/add-on

Preview attaching an add-on.

• Auth scope: read

Body

Field	Type	Required
subscriptionId	UUID	yes
addOnProductId	UUID	yes

Response 200

{
  "data": {
    "subscriptionId": "sub_01H...",
    "addOnProduct": { "id": "prod_c", "name": "Extra Seats", "priceCents": 1500, "currency": "USD" },
    "effectiveDate": "2026-05-02T14:01:23Z",
    "coTermToBase": true,
    "financialImpact": {
      "firstChargeCents": 750,
      "recurringPriceCents": 1500,
      "currency": "USD"
    },
    "businessRule": {
      "ruleId": "br_01H...",
      "ruleName": "Default add-on",
      "direction": "add_on",
      "changeTiming": "immediate",
      "prorationType": "prorated",
      "coTermToBase": true
    },
    "planDependencyAdjustments": []
  }
}

Errors

Status	When
404	Subscription or add-on product not found

cURL

curl -X POST https://api.example.com/api/v1/preview/add-on \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscriptionId": "sub_uuid", "addOnProductId": "prod_uuid" }'

---

POST /api/v1/preview/cancellation

Preview cancelling a subscription.

• Auth scope: read

Body

Field	Type	Required
subscriptionId	UUID	yes

Response 200

{
  "data": {
    "subscriptionId": "sub_01H...",
    "currentProduct": { "id": "prod_a", "name": "Starter", "priceCents": 1900 },
    "status": "active",
    "effectiveDate": "2026-06-01T00:00:00Z",
    "financialImpact": {
      "currentPriceCents": 1900,
      "refundCreditCents": 633,
      "currency": "USD"
    },
    "businessRule": {
      "ruleId": "br_01H...",
      "ruleName": "Standard cancellation",
      "direction": "cancellation",
      "changeTiming": "at_period_end",
      "prorationType": "none"
    },
    "policyEvaluation": {
      "allowed": true,
      "evaluations": []
    }
  }
}

Errors

Status	When
404	Subscription not found

cURL

curl -X POST https://api.example.com/api/v1/preview/cancellation \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscriptionId": "sub_uuid" }'

---

GET /api/v1/pricing/resolve

Resolve the effective price for a product given a customer context. Applies pricing tiers, quantity multipliers, and active offers.

• Auth scope: read

Query

Param	Type	Required	Description
productId	UUID	yes	Catalog product
segment	string (≤100)	no	Customer segment
locale	string (≤20)	no	e.g. en-US, de-DE
partner	string (≤255)	no	Partner ID
quantity	integer ≥ 1	no	Defaults to 1

Response 200

{
  "data": {
    "productId": "prod_01H...",
    "productName": "Pro Plan",
    "basePriceCents": 4900,
    "resolvedPriceCents": 4410,
    "currency": "USD",
    "quantity": 1,
    "context": { "segment": "smb", "locale": "en-US" },
    "rulesApplied": [
      {
        "rule": "Pricing tier: SMB monthly",
        "type": "pricing_tier",
        "adjustment": "+0 cents",
        "detail": "Matched tier \"SMB monthly\" (flat)"
      },
      {
        "rule": "Offer: Welcome 10% off (WELCOME10)",
        "type": "offer_discount",
        "adjustment": "-490 cents",
        "detail": "percentage discount of 10%"
      }
    ],
    "availableOffers": [
      { "id": "off_01H...", "code": "WELCOME10", "name": "Welcome 10% off", "discountType": "percentage", "discountValue": "10" }
    ]
  }
}

Errors

Status	When
400	Validation failed
404	Product not found

cURL

curl -G https://api.example.com/api/v1/pricing/resolve \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  --data-urlencode 'productId=prod_uuid' \
  --data-urlencode 'segment=smb' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'quantity=2'

---

Related

• Subscriptions — execute a previewed change

• Orders