Current plan and the ordered change, if any

GET

/subscription

const url = 'https://api.flotera.com/api/v1/subscription';
const options = {
  method: 'GET',
  headers: {cookie: '__Host-erm_session=<__Host-erm_session>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.flotera.com/api/v1/subscription \
  --cookie __Host-erm_session=<__Host-erm_session>

Authorizations

sessionCookie

Responses

200

Subscription view.

application/json

object

status

required

unassigned is not a plan: it means no assignment row exists yet, so nothing can be priced. Being on the free plan is active — free is a plan, not a subscription state (D-14).

string

Allowed values: active change_awaiting_payment downgrade_scheduled cancelled unassigned

plan

required

Any of:

object
null

object

code

required

Internal catalog code. Not the public label — labels are not unique.

string

<= 64 characters /^[a-z][a-z0-9_-]{1,63}$/

public_label

required

string

<= 64 characters

public_group

string | null

<= 64 characters

display_rank

integer

currency

required

string

Allowed value: USD

monthly_price_per_server_usd

null — contract-priced; such a plan is never published here.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

capabilities

required

Array<object>

<= 128 items

object

key

required

Entitlement key from 13 §3.3, e.g. fleet.servers.max.

string

<= 64 characters

value

required

Any of:

boolean

unlimited

True when an integer limit is explicitly unbounded.

boolean

monthly_price_per_server_usd

Frozen assignment price, which may differ from the catalog row.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

billing_effective_day

Any of:

string
null

UTC calendar day.

string format: date

managed_servers

required

integer

estimated_monthly_usd

Decimal string or null when unknown.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

pending_change

Any of:

object
null

object

required

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

status

required

string

Allowed values: scheduled awaiting_payment applied cancelled superseded expired rejected

direction

required

Direction at order time. It explains why the change is called a downgrade; it does not decide anything when the change fires — the rule is re-read then.

string

Allowed values: upgrade downgrade lateral

target_plan

required

Internal catalog code. Not the public label — labels are not unique.

string

<= 64 characters /^[a-z][a-z0-9_-]{1,63}$/

source_plan

Any of:

string
null

Internal catalog code. Not the public label — labels are not unique.

string

<= 64 characters /^[a-z][a-z0-9_-]{1,63}$/

effective_at

required

RFC 3339 UTC with microsecond precision.

string format: date-time

effective_day

required

First UTC day the new price applies to.

string format: date

required_reserve_usd

One day of the target plan at the current fleet size, when gated.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

topup_id

Any of:

string
null

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

rejected_reason

reserve_not_covered — the balance no longer covered the reserve when the change fired; direction_changed — the catalog price moved and an ordered downgrade would now be an upgrade, so it was refused instead of silently costing more.

string | null

<= 64 characters

requested_at

required

RFC 3339 UTC with microsecond precision.

string format: date-time

applied_at

RFC 3339 UTC with microsecond precision, or null.

string | null format: date-time

version

required

Send it back as If-Match to replace a pending change.

integer

generated_at

required

RFC 3339 UTC with microsecond precision.

string format: date-time

Example

{
  "status": "active",
  "plan": {
    "currency": "USD"
  },
  "pending_change": {
    "status": "scheduled",
    "direction": "upgrade",
    "effective_at": "2026-07-25T10:15:30.123456Z",
    "requested_at": "2026-07-25T10:15:30.123456Z"
  },
  "generated_at": "2026-07-25T10:15:30.123456Z"
}

Headers

ETag

string

<= 256 characters

Entity tag of the returned snapshot/resource version.

401

Missing/invalid credentials (code=unauthorized).

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

Allowed values: unauthorized forbidden csrf_rejected not_found conflict idempotency_conflict validation_failed rate_limited payload_too_large unsupported_agent_version temporarily_unavailable offline_queue_full online_queue_full plan_required server_limit_reached feature_not_entitled account_in_grace account_frozen payment_pending payment_expired payment_amount_mismatch change_already_pending change_already_applied change_effective reserve_not_covered direction_changed

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

403

Authenticated but not permitted. code=forbidden — role/scope mismatch; code=feature_not_entitled — the plan does not include the capability; code=account_frozen — the account is frozen and this operation is declared x-ermeon-frozen: deny. The three are deliberately distinct: only the last one is fixed by a top-up (13 §5.6).

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

503

A dependency the endpoint needs is not configured or is temporarily unavailable (code=unavailable). The rest of the API keeps working — an absent external integration must not take the service down.

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}