Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Preview (dry-run) a commitment purchase without creating it
Prices a prospective commitment purchase and returns its derived economics WITHOUT persisting
anything — a dry-run for the commitment creation form savings preview. Takes the same
CreateCommitmentInput payload as the create operation (commitment type, term, payment
option, committed hourly rate in ten-thousandths of the currency unit per hour, and the covered services) and returns the
effective discount fraction from the commitment discount table together with the derived on-demand
list rate, committed rate, covered quantity per hour, projected upfront and projected monthly savings.
The figures are computed against the REAL rate card exactly as the create derivation would, so the
client no longer has to mirror the backend discount table to render an accurate preview.
Validation: identical to create — type/term/payment must be valid enum members; hourly
must be a positive integer (ten-thousandths of the currency unit per hour); services must be a non-empty array of known service ids
(unknown id → 422 VALIDATION_FAILED); a covered family with no rated SKU in the scope's region → 422
VALIDATION_FAILED. Caller needs a billing-capable role (owner|admin|billing), else 403.
Async & state: Synchronous; NO state change — no commitment row is created and nothing is charged.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope; 422 field validation
failure; 500 internal failure.
Idempotency/Concurrency: Safe to repeat; no idempotency key required — the call never mutates.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
application/json- body
The commitment creation form submission payload.
type*CommitmentTypeCommitment product kind (Savings Plan / Reserved Instance).
"SAVINGS_PLAN""RESERVED"term*CommitmentTermCommitment term length.
"1yr""3yr"payment*CommitmentPaymentCommitment upfront payment option.
"ALL_UPFRONT""PARTIAL_UPFRONT""NO_UPFRONT"hourly*integerCommitted hourly rate in ten-thousandths of the currency unit per hour.
services*array<string>Covered service ids. Coverage is COMPUTE-ONLY: the only accepted id is compute (storage / network are no longer coverable). At least one required.
classScope?|Optional Savings-Plan scope to a single compute family class (e.g. GENERAL_PURPOSE); null means flexible across all eligible compute classes.
skuScope?|Reserved-Instance target: the specific compute flavor SKU (family+size) the RI covers, e.g. compute.instance.m1.large (a bare flavor name like m1.large is accepted and normalised). Required for RESERVED, ignored for SAVINGS_PLAN.
recommendationId?|Advisor recommendation id that pre-filled this purchase, when applicable.
Derived commitment economics for the given inputs; nothing was persisted.
application/json- response
Dry-run economics for a prospective commitment purchase (nothing persisted). Backs the the commitment creation form savings preview so the client reads the real discount + rate-card figures instead of mirroring the backend discount table.
type*CommitmentTypeCommitment product kind (Savings Plan / Reserved Instance).
"SAVINGS_PLAN""RESERVED"term*CommitmentTermCommitment term length.
"1yr""3yr"payment*CommitmentPaymentCommitment upfront payment option.
"ALL_UPFRONT""PARTIAL_UPFRONT""NO_UPFRONT"family*stringCovered family, resolved from the first selected service id.
region*stringRegion the rate card was priced in (the scope's default region).
discount*numberEffective discount vs on-demand for this (term, payment), 0..1.
hourly*integerCommitted hourly spend echoed from the request, in ten-thousandths of the currency unit per hour.
listRate*integerOn-demand list rate of the covered unit from the rate card, in ten-thousandths of the currency unit per hour.
committedRate*integerDiscounted committed rate of the covered unit, in ten-thousandths of the currency unit per hour.
coveredQtyPerHour*numberCovered units per hour back-solved from the committed hourly spend.
onDemandHourly*integerOn-demand-equivalent hourly spend for the covered quantity, in ten-thousandths of the currency unit per hour.
upfront*integerProjected upfront charge for the payment option over the term, in ten-thousandths of the currency unit.
upfrontTax?integerVAT on the projected upfront at the scope's current rate, in ten-thousandths of the currency unit.
0upfrontGross?integerThe gross the purchase would charge (upfront + VAT) -- what the customer must wire, in ten-thousandths of the currency unit.
0monthlySavings*integerProjected monthly savings vs on-demand at full utilization (30-day month), in ten-thousandths of the currency unit.
curl -X POST "https://example.com/scopes/string/billing/commitments/preview" \ -H "Content-Type: application/json" \ -d '{ "type": "SAVINGS_PLAN", "term": "1yr", "payment": "ALL_UPFRONT", "hourly": 0, "services": [ "string" ] }'{ "type": "SAVINGS_PLAN", "term": "1yr", "payment": "ALL_UPFRONT", "family": "string", "region": "string", "discount": 0, "hourly": 0, "listRate": 0, "committedRate": 0, "coveredQtyPerHour": 0, "onDemandHourly": 0, "upfront": 0, "upfrontTax": 0, "upfrontGross": 0, "monthlySavings": 0}