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.
Rename a subscription and/or change its billing country
Edits the subscription's display name (takes effect immediately; the id is frozen)
and/or its billingCountry. A billing-country change takes effect from the NEXT
billing period (first day of next month, UTC): every period already started keeps its
country, closed invoices keep their frozen subsidiary snapshot, and a second change before
then replaces the pending one. The response carries the country in force now and the
scheduled pendingBillingCountry.
Authorization: the subscription must be reached by the caller inside tenantId (else
404) and the caller must hold a SUBSCRIPTION-level owner grant on it -- a subscription grant
or a tenant grant (else 403; owning a project beneath it is not enough). An API
token is refused 403 TOKEN_SCOPE_MISSING (iam:write is never grantable). A tenant on
non-payment hold is refused 403 TENANT_SUSPENDED.
Validation: at least one of name / billingCountry (an empty body is 422); an unknown
field is 422 (never silently ignored). name follows the create rule (ASCII, a letter or
digit, 422 field=name) and must be unique (case-insensitive) among the tenant's
subscriptions (409 CONFLICT, field=name). billingCountry must match ^[A-Z]{2}$ and be
an allowed country (422 field=billingCountry, details.allowedBillingCountries). Every
refusal happens before any write.
Async & state: Synchronous; no Operation.
Errors: 401; 403; 404; 409 name clash; 422 validation; 500.
Idempotency/Concurrency: Naturally idempotent -- setting the current value again is a
no-op success; no Idempotency-Key is read.
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.
tenantId*stringThe tenant id.
subscriptionId*stringThe subscription id (unique platform-wide, derived from the tenant id + the subscription's name at creation).
application/json- body
Body of PATCH /tenants/{tenantId}/subscriptions/{subscriptionId}. At least one of the two fields is required.
1 <= propertiesname?|New display name, immediate; unique among the tenant's subscriptions.
billingCountry?|New billing country, effective from the next billing period.
^[A-Z]{2}$The subscription after the edit.
application/json- response
Subscription summary.
id*stringtenantId*stringname*stringcurrency*CurrencyCodeISO currency code supported by billing.
"USD""EUR""TRY"defaultRegion*RegionIdPlatform region code (a DNS-label-shaped slug, e.g. ist-1). No longer a closed enum: the set of valid region codes is operator-managed in the platform-region registry, so this carries only a shape guard. The authoritative set of activated regions is read from GET /regions; invalid-shape codes are VALIDATION_FAILED and codes absent from the registry are rejected at the resolving endpoint.
^[a-z][a-z0-9-]{1,39}$billingCountry?|ISO 3166-1 alpha-2 billing country of the subscription IN FORCE NOW. It picks the subsidiary (issuing legal entity) that invoices the subscription and the tax-matrix country. Cycle close uses the country in force at the start of the billing period, so a change takes effect from the next period. Required on create (only a country with an explicit issuing subsidiary + tax mapping is accepted). Null only for a subscription with no recorded country.
^[A-Z]{2}$pendingBillingCountry?|A scheduled billing-country change (effective from the next billing period), or null.
curl -X PATCH "https://example.com/tenants/string/subscriptions/string" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "string", "tenantId": "string", "name": "string", "currency": "USD", "defaultRegion": "string", "billingCountry": "string", "pendingBillingCountry": { "country": "string", "effectiveFrom": "2019-08-24T14:15:22Z" }}