What the Premier upgrade would charge today and at renewal
const url = 'https://api.tovarifinancial.com/billing/stripe/subscription/plan/preview?planCode=premier&interval=month';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.tovarifinancial.com/billing/stripe/subscription/plan/preview?planCode=premier&interval=month' \ --header 'Authorization: Bearer <token>'Read-only. The payment provider’s own invoice preview for exactly the upgrade POST /billing/stripe/subscription/plan would make, passed through as integer minor units: amountDueTodayCents (tax included, unused Fundamentals time credited), nextRenewalCents (the Premier price for the interval, before tax) and nextRenewalAt. Nothing is charged or changed, and no client computes a prorated amount.
Only the household admin or the member who started the subscription may change it (403 FORBIDDEN). A target other than premier is 409 SUBSCRIPTION_CHANGE_UNAVAILABLE (switching to Fundamentals is cancel and resubscribe); so is a subscription that is set to end or whose payment is past due. A subscription already on Premier is 409 SUBSCRIPTION_ALREADY_ACTIVE. 404 when the household has no running web subscription. 503 when Premier is not sold for that interval, or the running price maps to no plan.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The plan to preview moving to. Only premier is an upgrade.
The Premier interval to preview.
Responses
Section titled “Responses”The preview
object
object
Charged now if the upgrade is made, integer minor units.
The Premier price the subscription renews at, before tax.
When the subscription next renews after the upgrade.
Example
{ "data": { "currency": "USD" }}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend. This operation can ALSO answer 403 with errorCode FORBIDDEN, which is a refusal by the TARGET RESOURCE rather than by the tenant gate: a built-in section or category that cannot be edited, deleted or budgeted, a category whose kind cannot carry a target amount, or a web subscription that only the household admin or the member who started it may change. That arm carries no details, says nothing about the caller’s account standing, and — unlike the three gate codes — is not cleared by resolving anything on the account: address a different resource, or ask someone who may change it, instead. It is INDEPENDENT of BILLING_ENABLED, so the reachable set here is three codes today (the two gate codes above plus FORBIDDEN) and four once billing is on. The errorCode enum on this operation’s response schema is the complete, machine-readable list.
object
Which condition refused the request. The first three are the tenant gate, evaluated in that order (CCR-1), and SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true. FORBIDDEN is a refusal by the target resource itself (or, on POST /invites, by the caller’s household role) and carries no details.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Resource not found or not owned by the caller org
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Conflict. errorCode is IDEMPOTENCY_CONFLICT when an X-Idempotency-Key was replayed with a different request payload; where the operation instead detects a resource-state conflict it carries that endpoint’s own errorCode (a duplicate name, an import that is no longer committable, an account already linked to a bank connection).
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}