Identity & Access Management

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

PATCH
/tenants/{tenantId}/subscriptions/{subscriptionId}

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.

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

tenantId*string

The tenant id.

subscriptionId*string

The subscription id (unique platform-wide, derived from the tenant id + the subscription's name at creation).

Request Body

application/json
  1. body

Body of PATCH /tenants/{tenantId}/subscriptions/{subscriptionId}. At least one of the two fields is required.

Properties1 <= properties
name?|

New display name, immediate; unique among the tenant's subscriptions.

billingCountry?|

New billing country, effective from the next billing period.

Match^[A-Z]{2}$

Response Body

The subscription after the edit.

application/json
  1. response

Subscription summary.

id*string
tenantId*string
name*string
currency*CurrencyCode

ISO currency code supported by billing.

Value in"USD""EUR""TRY"
defaultRegion*RegionId

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

Match^[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.

Match^[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"  }}