Billing & FinOps

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

POST
/scopes/{scopeId}/billing/commitments/preview

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Request Body

application/json
  1. body

The commitment creation form submission payload.

type*CommitmentType

Commitment product kind (Savings Plan / Reserved Instance).

Value in"SAVINGS_PLAN""RESERVED"
term*CommitmentTerm

Commitment term length.

Value in"1yr""3yr"
payment*CommitmentPayment

Commitment upfront payment option.

Value in"ALL_UPFRONT""PARTIAL_UPFRONT""NO_UPFRONT"
hourly*integer

Committed 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.

Response Body

Derived commitment economics for the given inputs; nothing was persisted.

application/json
  1. 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*CommitmentType

Commitment product kind (Savings Plan / Reserved Instance).

Value in"SAVINGS_PLAN""RESERVED"
term*CommitmentTerm

Commitment term length.

Value in"1yr""3yr"
payment*CommitmentPayment

Commitment upfront payment option.

Value in"ALL_UPFRONT""PARTIAL_UPFRONT""NO_UPFRONT"
family*string

Covered family, resolved from the first selected service id.

region*string

Region the rate card was priced in (the scope's default region).

discount*number

Effective discount vs on-demand for this (term, payment), 0..1.

hourly*integer

Committed hourly spend echoed from the request, in ten-thousandths of the currency unit per hour.

listRate*integer

On-demand list rate of the covered unit from the rate card, in ten-thousandths of the currency unit per hour.

committedRate*integer

Discounted committed rate of the covered unit, in ten-thousandths of the currency unit per hour.

coveredQtyPerHour*number

Covered units per hour back-solved from the committed hourly spend.

onDemandHourly*integer

On-demand-equivalent hourly spend for the covered quantity, in ten-thousandths of the currency unit per hour.

upfront*integer

Projected upfront charge for the payment option over the term, in ten-thousandths of the currency unit.

upfrontTax?integer

VAT on the projected upfront at the scope's current rate, in ten-thousandths of the currency unit.

Default0
upfrontGross?integer

The gross the purchase would charge (upfront + VAT) -- what the customer must wire, in ten-thousandths of the currency unit.

Default0
monthlySavings*integer

Projected 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}