Skip to content
nsin nsin nsin Docs

List services across all my clients

GET
/reseller/v1/services
 
curl --request GET \
  --url 'https://api.nsin.cloud/reseller/v1/services?page=1&per_page=25&status=active' \
  --header 'Authorization: Bearer <token>'

Every subscription belonging to every one of the caller’s clients — the selling surface, so each row carries plan_term_id, the price_rials the client’s wallet was debited, and the id you hand to change-plan and DELETE /services/{serviceId}. (GET /subscriptions is the same rows shaped for operating: expiry-sorted, filterable by days-to-expiry, no prices.)

client_id is intersected with your own clients rather than trusted, so naming another reseller’s client returns an empty page, not a 403 — and so does a status value outside the enum.

Each row also reports the state of the domain behind the service (domain_name, domain_disabled, domain_disabled_reason, domain_deleted), read unscoped so a soft-deleted domain still resolves to a name instead of a bare id. An active service can sit on a domain that is switched off, or on one that has been deleted; read those fields before you report a customer as healthy. Newest first, per_page default 25, clamped to 100.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
page
integer
default: 1 >= 1
per_page
integer
default: 25 >= 1 <= 100
client_id
integer
status

Mirrors subscriptions.status exactly.

There is deliberately no suspended value. Suspension is not a subscription state in NSIN — it is domains.suspended, a boolean on the domain, and that is the thing the edge actually checks before serving.

So: expired and cancelled mean “no plan, still serving”. They are not an off switch. The off switch is POST /domains/{domainId}/disable.

A domain in that state has an allowance of zero and — because a reseller’s client has no pay-as-you-go — is suspended by the quota sweep as soon as it serves a byte. It stops shortly; it does not run up a bill. But “shortly” is not “now”, which is why the explicit domain suspend exists.

TODO (deferred): a first-class suspended status on the subscription itself, so a service can be frozen without touching the domain row. Not needed for v1 — domain suspend already stops serving and stops the meter, which is the entire business requirement. See the Deferred table in RESELLER_PLAN_V2.md.

string
Allowed values: active grace expired cancelled

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A page of services

Media type application/json
object
data
required
Array<object>

A subscription. Not a new entity — this is the subscriptions row.

The plan is reported three ways on purpose, so a reseller can always see which plan is active and what it cost without a second lookup: plan_id + plan_name (which plan), duration_days (which term), and price_rials (what the client’s wallet was actually debited).

object
id
required
integer
client_id
required
integer
domain_id
required
integer
domain_name
string
domain_disabled

Whether the domain behind this service is currently being served.

A service can be active while its domain is off. The plan is paid for; the traffic is not flowing. Read this before reporting a service as healthy.

boolean
domain_disabled_reason

Present only when domain_disabled is true. manual is yours to lift with POST /domains/{domainId}/enable; the other two are the system’s and that call returns 409.

string
Allowed values: manual quota_exceeded negative_balance
plan_id
required

Which plan is active. Free / Starter / Golden / Enterprise.

integer
plan_name
required
string
plan_term_id
required
integer
duration_days
required

The term that was bought. The same plan at a different duration is a different price.

integer
price_rials
required

NSIN list price of this term — what the client’s wallet was debited at purchase. 0 for the Free plan, which is a real, purchasable plan (the debit is simply a no-op).

integer format: int64
status
required

Mirrors subscriptions.status exactly.

There is deliberately no suspended value. Suspension is not a subscription state in NSIN — it is domains.suspended, a boolean on the domain, and that is the thing the edge actually checks before serving.

So: expired and cancelled mean “no plan, still serving”. They are not an off switch. The off switch is POST /domains/{domainId}/disable.

A domain in that state has an allowance of zero and — because a reseller’s client has no pay-as-you-go — is suspended by the quota sweep as soon as it serves a byte. It stops shortly; it does not run up a bill. But “shortly” is not “now”, which is why the explicit domain suspend exists.

TODO (deferred): a first-class suspended status on the subscription itself, so a service can be frozen without touching the domain row. Not needed for v1 — domain suspend already stops serving and stops the meter, which is the entire business requirement. See the Deferred table in RESELLER_PLAN_V2.md.

string
Allowed values: active grace expired cancelled
started_at
required
string format: date-time
expires_at
required
string format: date-time
grace_until
string format: date-time
nullable
auto_renew
boolean
meta
required
object
page
required
integer
per_page
required
integer
total
required
integer
Example 
{
  "data": [
    {
      "domain_name": "example.com",
      "domain_disabled_reason": "manual",
      "plan_id": 3,
      "plan_name": "Golden",
      "plan_term_id": 14,
      "duration_days": 365,
      "price_rials": 120000000,
      "status": "active"
    }
  ]
}

400

Section titled “400 ”

Malformed or invalid input.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object
error
required
string
code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

  • credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
  • domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
  • unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
  • rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
  • session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.
string
Example 
{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

401

Section titled “401 ”

Missing, malformed, expired, or revoked credential.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object
error
required
string
code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

  • credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
  • domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
  • unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
  • rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
  • session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.
string
Example 
{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

403

Section titled “403 ”

Authenticated, but the target does not belong to you — or you are not a reseller at all.

This is the response the tenant-isolation matrix asserts on. Every route in this document is called with reseller B’s credential against reseller A’s ids, and must answer 403 or 404 with none of A’s data in the body.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object
error
required
string
code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

  • credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
  • domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
  • unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
  • rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
  • session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.
string
Example 
{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

429

Section titled “429 ”

The caller’s request budget is spent. 300 requests per minute by default (RESELLER_RATE_LIMIT), and the same limiter covers every one of the 83 operations in this document.

Counted per credential, not per reseller: each nsin_live_ token has its own budget and a dashboard session has another, so one runaway integration cannot lock its owner out of his own panel, and revoking that token is enough to stop it.

Branch on "code": "rate_limited" in the body. The message beside it is written for a human and may be reworded.

Retry-After is set, in seconds until the window resets — wait that long rather than retrying at once. The X-RateLimit-* headers are not on this response; they appear only on the responses the limiter let through, so a client that reads its remaining budget from the 429 alone will never see one.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object
error
required
string
code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

  • credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
  • domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
  • unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
  • rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
  • session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.
string
Example 
{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the current window resets.

500

Section titled “500 ”

Something failed on our side. The body carries a human sentence and never an internal detail — a live sweep of this API once returned dial tcp 127.0.0.1:9000: connect: connection refused, which is our topology rather than an error message. That is now impossible.

Distinguish it from 503. A 503 means a dependency is down and the identical request will succeed later, so retry it. A 500 means the request hit a genuine fault: retrying it unchanged will fail the same way, and it should be reported with the X-Request-Id from the response header.

Declared on every operation because every operation can reach it. It was previously declared on exactly one, which left a generated client with no branch for the answer it is most likely to be surprised by.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object
error
required
string
code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

  • credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
  • domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
  • unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
  • rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
  • session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.
string
Example 
{
  "error": "forbidden",
  "code": "credit_limit_reached"
}