Skip to content
OTA-Pulse Docs

Get Subscription

GET
/api/billing/subscription
 
curl --request GET \
  --url 'https://example.com/api/billing/subscription?organization_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --header 'Authorization: Bearer <token>'

An org’s per-product entitlement state plus month-to-date usage.

Entitlement state is dunning-ladder normalized (_normalize_entitlement_state, app/core/deps.py) rather than the raw DB value, so this endpoint can never show a stale trial/grace row that the sweep job (entitlement_sweep.py) hasn’t persisted yet — same posture as RequireEntitlement.

Usage covers every (product, meter) with at least one organization_usage_counters row this UTC calendar month. limit is the EFFECTIVE ceiling, resolved in §13.6’s exact order (this field is asserted on by billing_flows, so the order has to be unambiguous):

  1. product in trial -> the S39 trial ceiling (app/config.py’s billing_trial_* settings via ingest_gate._trial_limit, the exact function the ingest gate enforces against), unchanged;
  2. else, org on a tier -> that tier’s included amount for the meter;
  3. else — a grandfathered à la carte org, or a meter with no quota dimension — None, exactly as before. Such an org has no hard ceiling, only a billed overage.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “ Query Parameters ”
organization_id
required
Organization Id
string format: uuid

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Successful Response

Media type application/json
BillingSubscriptionResponse

GET /api/billing/subscription — org-scoped entitlement + usage summary.

object
entitlements
required
Entitlements
Array<object>
ProductEntitlementItem

One product’s current entitlement state for an organization.

object
plan_code
Any of:
string
product
required
Product
string
state
required
State
string
trial_ends_at
Any of:
string format: date-time
has_mcu_ota
Has Mcu Ota
boolean
organization_id
required
Organization Id
string format: uuid
overage_enabled
Overage Enabled
boolean
plan_code
Any of:
string
storage_quota_bytes
Any of:
integer
storage_used_bytes
Storage Used Bytes
integer
0
tier_rank
Any of:
integer
usage
required
Usage
Array<object>
UsageMeterItem

Month-to-date usage for one (product, meter) with any activity this month.

object
dropping
Dropping
boolean
limit
Any of:
integer
meter
required
Meter
string
month_to_date
required
Month To Date
integer
overage_available
Overage Available
boolean
period_resets_at
required
Period Resets At
string format: date-time
product
required
Product
string
Example 
{
  "has_mcu_ota": false,
  "overage_enabled": false,
  "storage_used_bytes": 0,
  "usage": [
    {
      "dropping": false,
      "overage_available": false
    }
  ]
}

422

Section titled “ 422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated 
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}