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.

List the spend-threshold campaigns the active scope takes part in, with progress

GET
/scopes/{scopeId}/billing/campaigns

Returns the platform's "spend X, earn Y" campaigns that apply to this tenant, as rendered by the campaign card on the Credits page. A campaign applies when it is denominated in the subscription's currency, has not passed its paymentDeadline (endsAt + 14 days) and is either running (active, started) or has already rewarded this tenant. Participation is automatic (no code, no opt-in). counted is the tenant's qualifying spend so far, in ten-thousandths of the campaign currency's unit: the tax-exclusive share of every PAID invoice issued inside the campaign window that was paid in cash or with prepaid credit (the share paid with coupon / promo / support credit does not count; UNPAID, OVERDUE and CANCELLED invoices do not count; an invoice paid later than 14 days after endsAt does not count; invoices of other currencies do not count). Once counted reaches threshold the tenant receives ONE promo credit grant of reward (valid for rewardValidityDays), at most once per campaign per tenant; earned, earnedAt and creditId then describe that grant. Validation: scopeId must reference a tenant/subscription/project scope the caller can access — unknown or unauthorized scope maps to 404 NOT_FOUND. No other inputs. Async & state: Synchronous read; no state change. No SSE frames are emitted. Errors: 401 unauthenticated; 403 caller lacks billing read access in the scope; 404 unknown scopeId; 500 read failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

Response Body

The campaigns that apply to the scope's tenant, with progress (possibly empty).

application/json
  1. response
data*array<>
curl -X GET "https://example.com/scopes/string/billing/campaigns"
{  "data": [    {      "id": "camp-7f3a",      "name": "200 harca 500 kazan",      "currency": "TRY",      "threshold": 0,      "reward": 0,      "startsAt": "2019-08-24T14:15:22Z",      "endsAt": "2019-08-24T14:15:22Z",      "paymentDeadline": "2019-08-24T14:15:22Z",      "rewardValidityDays": 0,      "counted": 0,      "earned": true,      "earnedAt": "2019-08-24T14:15:22Z",      "creditId": "string"    }  ]}