Get the domain's current subscription

GET

/domains/{domain}/subscription

const url = 'https://api.nsin.ir/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.ir/domains/example.com/subscription \
  --header 'Authorization: Bearer <token>'

The active subscription, its period statement, its invoices and the wallet movements tied to it. 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

transactions

Wallet movements belonging to this subscription — the purchase debit, renewal debits and any refunds of its invoices — newest first. Empty when the term was never paid from the wallet.

Array<object>

object

integer

wallet_id

integer

user_id

integer

type

string

Allowed values: topup purchase refund admin_adjust

amount_rials

Signed — positive credits, negative debits.

integer

balance_after

integer

description

string

ref_type

What the row refers to — payment, subscription, traffic or manual.

string

ref_id

integer

ref_code

Payment gateway reference, for top-ups.

string

created_at

string format: date-time

domain_id

Set on traffic charges.

integer

domain_name

Set on traffic charges.

string

Example

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

400

Missing domain.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

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

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

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 single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

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

429

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

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}