Get the domain's current subscription

GET

/domains/{domain}/subscription

const url = 'https://api.nsin.cloud/domains/example.com/subscription';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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.nsin.cloud/domains/example.com/subscription \
  --header 'Authorization: Bearer <token>'

The active subscription, its period statement and its invoices. Returns null when the domain has no subscription. Readable by shared members, not only the owner.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Responses

200

Current subscription, or null.

application/json

One of:

null
object

null

object

subscription

A plan attached to one domain. Entitlements are not read from the plan directly — use GET /domains/{domain}/features, which resolves any per-subscription overrides.

object

integer

user_id

integer

domain_id

integer

domain_name

string

plan_id

integer

plan

The plan this subscription is on.

object

key

additional properties

any

plan_term_id

integer

plan_term

The billing term purchased.

object

key

additional properties

any

status

For example active, expired, grace or cancelled.

string

started_at

string format: date-time

expires_at

string format: date-time

grace_until

string format: date-time

auto_renew

boolean

quota_reset_days

Traffic-allowance reset cadence, frozen at purchase time so later plan changes cannot shift an existing subscriber’s quota window.

integer

is_trial

The free trial granted at signup. Downgrades to the free plan on expiry rather than entering grace.

boolean

period_statement

One billing period’s cost. For the period in progress the traffic figures are a running estimate.

object

integer

subscription_id

integer

plan_id

integer

plan_name

string

plan_term_id

integer

billing_duration_days

integer

quota_reset_days

integer

period_start

string

period_end

string

plan_price_rials

integer

traffic_cached_bytes

integer

traffic_proxied_bytes

integer

traffic_direct_bytes

integer

traffic_bypass_bytes

Legacy two-tier column, on historical periods only.

integer

traffic_charged_rials

integer

by_domain

Array<object>

object

domain

string

cached_bytes

integer

proxied_bytes

integer

direct_bytes

integer

estimated_charged_rials

integer

invoices

Array<object>

object

integer

number

Human-facing invoice number, sequential per Jalali year.

string

user_id

integer

domain_id

integer

domain_name

string

subscription_id

integer

payment_id

integer

kind

string

Allowed values: subscription topup manual

status

string

Allowed values: paid unpaid cancelled

subtotal_rials

integer

tax_rials

integer

total_rials

integer

issued_at

string format: date-time

paid_at

string format: date-time

notes

string

created_at

string format: date-time

updated_at

string format: date-time

items

Array<object>

object

integer

invoice_id

integer

description

string

quantity

integer

unit_price_rials

integer

total_rials

integer

Example

{
  "invoices": [
    {
      "kind": "subscription",
      "status": "paid"
    }
  ]
}

400

Missing domain.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string

Example

{
  "error": "read-only API key"
}

401

Missing, malformed, revoked or expired API key, or a key whose owning user row is gone. A key whose owning account has merely been deactivated is not this: that is 403 with code: account_suspended, because the credential itself is intact and re-issuing it changes nothing.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Examples

limited

{
  "error": "rate limit exceeded"
}