Preview

The Preview API runs the same business-rule and pricing-engine logic as the corresponding mutating endpoints, but returns the planned outcome without committing it. It exists so that customer-facing UIs (and CSR / partner consoles) can show the effective date, proration, retention requirements, and which rule will apply before the customer clicks Confirm.

There is one preview endpoint per high-impact subscription transition:

POST /preview/plan-change — what would happen if we moved this subscription to that product?
POST /preview/cancellation — when would the cancel take effect, what refund / credit follows, and is a retention step required first?
POST /preview/add-on — when would the add-on start, will it co-term, and what is the prorated first charge?

Each response includes effectiveDate, the resolved businessRule (its id, name, and key parameters), the resolved pricing block (delegated to /pricing/resolve), and any requirements the UI must satisfy before calling the matching mutator (e.g. capture a retention reason).

Previews are read-only and write nothing to the audit log. They require the read scope.

Endpoints

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

Preview adding an add-on to a subscription: returns effective date, co-term behavior, prorated first charge, and applicable business rule

post

/preview/add-on

Authorizations

X-API-KeystringRequired

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

Body

subscriptionIdstringRequired

addOnProductIdstringRequired

Responses

200

Add-on preview

application/json

Preview of an operation showing effective date, financial impact, applicable business rule, and policy evaluation. Read-only — no state changes.

subscriptionIdstringOptional

currentProductobject · nullableOptional

targetProductobject · nullableOptional

directionstring · enumOptionalPossible values:

effectiveDatestring · date-timeOptional

businessRuleobject · nullableOptional

The business rule governing this operation, or null if no rule applies

resolvedPriceobjectOptional

Resolved pricing including tier information

404

Subscription or product not found

post/preview/add-on

POST /api/v1/preview/add-on HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "subscriptionId": "text",
  "addOnProductId": "text"
}

{
  "subscriptionId": "text",
  "currentProduct": {},
  "targetProduct": {},
  "direction": "upgrade",
  "effectiveDate": "2026-07-14T00:28:04.002Z",
  "financialImpact": {
    "currentPriceCents": 1,
    "newPriceCents": 1,
    "creditCents": 1,
    "chargeCents": 1,
    "netCents": 1,
    "currency": "text"
  },
  "businessRule": {},
  "policyEvaluation": {
    "allowed": true,
    "evaluations": [
      {}
    ]
  },
  "resolvedPrice": {}
}

Computes the result of attaching addOnProductId to subscriptionId without applying it. The response carries the effectiveDate (which can be "immediate", the next bill cycle, or aligned to the parent subscription's term depending on the matching business rule), whether the add-on will be co-termed to the base subscription, the prorated first charge, and the businessRule that drove these decisions.

Pair with POST /subscriptions/{id}/change-plan (or the dedicated add-on mutator if your integration uses one) to commit. Returns 404 when either id is not found in the tenant's catalog or subscription set.

`POST /api/v1/preview/cancellation`

Preview cancelling a subscription: returns effective date, refund/credit info, retention requirements, and applicable business rule

post

/preview/cancellation

Authorizations

X-API-KeystringRequired

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

Body

subscriptionIdstringRequired

Responses

200

Cancellation preview

application/json

Preview of an operation showing effective date, financial impact, applicable business rule, and policy evaluation. Read-only — no state changes.

subscriptionIdstringOptional

currentProductobject · nullableOptional

targetProductobject · nullableOptional

directionstring · enumOptionalPossible values:

effectiveDatestring · date-timeOptional

businessRuleobject · nullableOptional

The business rule governing this operation, or null if no rule applies

resolvedPriceobjectOptional

Resolved pricing including tier information

404

Subscription not found

post/preview/cancellation

POST /api/v1/preview/cancellation HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "subscriptionId": "text"
}

{
  "subscriptionId": "text",
  "currentProduct": {},
  "targetProduct": {},
  "direction": "upgrade",
  "effectiveDate": "2026-07-14T00:28:04.002Z",
  "financialImpact": {
    "currentPriceCents": 1,
    "newPriceCents": 1,
    "creditCents": 1,
    "chargeCents": 1,
    "netCents": 1,
    "currency": "text"
  },
  "businessRule": {},
  "policyEvaluation": {
    "allowed": true,
    "evaluations": [
      {}
    ]
  },
  "resolvedPrice": {}
}

Computes the result of cancelling subscriptionId without applying it. The response includes the effectiveDate and a human-readable effectiveDateLabel derived from the matching cancellation rule's changeTiming — immediate, end_of_term, custom_delay, or grace_period are all honored end-to-end, so admin edits to a cancellation rule's timing flow straight through this preview without any code change. Cancellation rule selection follows the shared product → category → tenant-global → platform-default precedence, so multi-rule tenants always get the most specific cancellation rule for the subscription's product. The response also surfaces the refund or credit the customer would receive, any retentionRequirements the UI must satisfy first (e.g. capture a reason, present a save offer), and the matching businessRule for transparency.

Use the result to render the cancellation confirmation modal; commit by calling POST /subscriptions/{id}/cancel.

Plan-change and add-on previews resolve their effective-date timing through the same shared business-rule resolver and pass product/category hints (target product + current product for plan-change; the add-on product itself for add-on) so product- and category-scoped tenant rules win over tenant-global and platform-default rows. Admin edits to a tenant's product-scoped rule take effect on the very next preview without code changes.

`POST /api/v1/preview/order-total`

Preview an order total: returns subtotal, tax, and shipping breakdown without creating an order. Calls the pluggable tax and shipping hooks configured for this tenant.

post

/preview/order-total

Authorizations

X-API-KeystringRequired

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

Body

currencystringOptionalDefault: USD

shippingOptionIdstringOptional

customerContextobjectOptional

Responses

200

Order total preview with subtotal, tax, and shipping breakdown

application/json

Breakdown of an order total including line items, tax, and shipping. Read-only — does not create an order.

subtotalCentsintegerOptional

taxAmountCentsintegerOptional

shippingAmountCentsintegerOptional

grandTotalCentsintegerOptional

currencystringOptional

400

Validation error

application/json

post/preview/order-total

POST /api/v1/preview/order-total HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 339

{
  "items": [
    {
      "productId": "text",
      "name": "text",
      "quantity": 1,
      "unitPriceCents": 1
    }
  ],
  "currency": "USD",
  "shippingOptionId": "text",
  "shippingAddress": {
    "country": "text",
    "state": "text",
    "postalCode": "text",
    "city": "text",
    "line1": "text"
  },
  "taxAddress": {
    "country": "text",
    "state": "text",
    "postalCode": "text",
    "city": "text",
    "line1": "text"
  },
  "customerContext": {}
}

{
  "subtotalCents": 1,
  "taxAmountCents": 1,
  "shippingAmountCents": 1,
  "grandTotalCents": 1,
  "currency": "text",
  "tax": {
    "amountCents": 1,
    "rate": 1,
    "provider": "text",
    "breakdown": [
      {
        "description": "text",
        "amountCents": 1,
        "rate": 1
      }
    ]
  },
  "shipping": {
    "selectedOption": {
      "id": "text",
      "name": "text",
      "carrier": "text",
      "estimatedDays": 1,
      "priceCents": 1,
      "currency": "text",
      "description": "text"
    },
    "availableOptions": [
      {
        "id": "text",
        "name": "text",
        "carrier": "text",
        "estimatedDays": 1,
        "priceCents": 1,
        "currency": "text",
        "description": "text"
      }
    ]
  },
  "pricingBreakdown": [
    {
      "productId": "text",
      "name": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "lineTotalCents": 1,
      "priceSource": "pricing_engine"
    }
  ]
}

Notes, examples, or caveats for POST /preview/order-total go here.

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

Preview a plan change: returns effective date, proration, applicable business rule, and resolved price without executing the change

post

/preview/plan-change

Authorizations

X-API-KeystringRequired

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

Body

subscriptionIdstringRequired

targetProductIdstringRequired

Responses

200

Plan change preview

application/json

Preview of an operation showing effective date, financial impact, applicable business rule, and policy evaluation. Read-only — no state changes.

subscriptionIdstringOptional

currentProductobject · nullableOptional

targetProductobject · nullableOptional

directionstring · enumOptionalPossible values:

effectiveDatestring · date-timeOptional

businessRuleobject · nullableOptional

The business rule governing this operation, or null if no rule applies

resolvedPriceobjectOptional

Resolved pricing including tier information

404

Subscription or product not found

post/preview/plan-change

POST /api/v1/preview/plan-change HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "subscriptionId": "text",
  "targetProductId": "text"
}

{
  "subscriptionId": "text",
  "currentProduct": {},
  "targetProduct": {},
  "direction": "upgrade",
  "effectiveDate": "2026-07-14T00:28:04.002Z",
  "financialImpact": {
    "currentPriceCents": 1,
    "newPriceCents": 1,
    "creditCents": 1,
    "chargeCents": 1,
    "netCents": 1,
    "currency": "text"
  },
  "businessRule": {},
  "policyEvaluation": {
    "allowed": true,
    "evaluations": [
      {}
    ]
  },
  "resolvedPrice": {}
}

Computes the result of moving subscriptionId to targetProductId without applying it. The response includes effectiveDate (immediate vs end-of-term), the prorated charge or credit, the matching businessRule, and the resolved unit price for the target plan (via the Pricing API).

Use the response to populate the plan-change confirmation dialog; commit by calling POST /subscriptions/{id}/change-plan with the same targetProductId. Returns 404 when either the subscription or the target product is not in the tenant's catalog.

PreviousPayments NextPricing

Last updated 16 days ago

Was this helpful?