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.

Retry a failed payment (retired — always CONFLICT)

Deprecated

POST
/scopes/{scopeId}/billing/transactions/{transactionId}/actions/retry

Retired. This action refuses every transaction with CONFLICT and is proposed for removal. It described a card re-charge — "initiated with the scope's default payment method", "Issuer declined — insufficient funds (code 51)", "never issues a second processor charge" — and the platform stores no cards and runs no payment processor, so there is nothing to re-attempt. paymentMethodId was already deprecated and ignored. What it did instead was settle the entry offline: a failed entry became completed and its linked invoice flipped PAID. That is settlement, which belongs to a platform Finance operator alone, and it was reachable by an ordinary tenant in two calls (cancel an invoice charge to failed, then retry it). Re-submitting a withdrawn payment is a different thing and does not need this action: submit a new one through the invoice pay endpoint, which records a fresh pending-manual-approval entry and leaves the withdrawn one intact for audit. Validation: transaction must exist in the scope (else NOT_FOUND, so an absent or cross-scope id is not distinguishable from a refused one); caller needs contributor/admin/owner or billing role, otherwise FORBIDDEN. Every resolvable transaction then answers CONFLICT regardless of type or status. Nothing is written under any code path. Async & state: none — the action never reaches a state transition. The 202 Operation response below is retained for schema compatibility and is no longer returned. Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope/transaction; 409 CONFLICT always. Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted and a sent one is ignored. Every call is refused (404 for an unknown entry, otherwise 409 CONFLICT) and nothing is written, so repeating it has no effect.

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.

transactionId*string

Failed transaction ledger entry identifier.

Request Body

application/json
  1. body

Optional input for retrying a failed payment; the entry is re-settled OFFLINE (bank transfer).

paymentMethodId?|Deprecated

Deprecated: the platform stores no cards and runs no PSP — retry re-settles offline. This field is IGNORED and will be removed once the Payment methods UI is retired.

Response Body

Retry accepted; track settlement via the returned operation.

application/json
  1. response

A long-running operation record. GET /operations/{operationId} returns its current state.

id*string

Operation identifier, unique platform-wide.

action*string

Canonical action id that started this operation, e.g. compute.instance.create.

state*OperationState

State machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.

Value in"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"
resourceKind?|

Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.

resourceId?|

Identifier of the target resource; null until the resource is allocated.

resourceName?|

Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).

principalId?|

Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.

sourceIp?|

Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).

progressPercent?|

Best-effort progress; null when the action does not report progress.

Range0 <= value <= 100
error?|null

Populated only when state is FAILED (or CANCELLED with partial rollback notes).

warning?|null

Non-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.

startedAt?|

When the worker began executing; null while PENDING.

finishedAt?|

When a terminal state was reached; null while transitional.

createdAt*string
updatedAt*string
curl -X POST "https://example.com/scopes/string/billing/transactions/string/actions/retry" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "action": "string",  "state": "PENDING",  "resourceKind": "string",  "resourceId": "string",  "resourceName": "string",  "principalId": "string",  "sourceIp": "string",  "progressPercent": 0,  "error": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "warning": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "startedAt": "string",  "finishedAt": "string",  "createdAt": "string",  "updatedAt": "string"}