Get subscription status

Summary

Returns the current state of a subscription owned by the calling merchant. Use this to reconcile state — for example, after the user is redirected back from a web-init flow, or to detect cancellations applied carrier-side.

Path

POST https://merchants.noju.io/subscriptions/status

Headers

Header	Required	Value
API-KEY	yes	Your merchant API key.
Content-Type	yes	application/json

Request body

Field	Type	Required	Description
subscription_id	string	yes	The subscription's public UUID.

Success payload

On status: "SUCCESS", payload contains:

Field	Type	Description
subscription_id	string	Echo of the requested ID.
status	string	Subscription state (e.g. ACTIVE, CANCELED, EXPIRED).
msisdn	string	The subscriber's MSISDN.
service_code	string	The service code for this subscription.
service_name	string	Human-readable service name.
subscribed_dt	string (ISO-8601) | null	When the subscription was first activated.
expiry_dt	string (ISO-8601) | null	When the subscription expires. Re-billing will be attempted on this date.
canceled_dt	string (ISO-8601) | null	When the subscription was canceled.
content_link	string | null	URL to service content, if applicable.

Errors

HTTP	message	When
400	BAD_REQUEST	Body fails JSON schema validation.
401	UNAUTHORIZED	API key missing, invalid, or merchant inactive.
403	UNAUTHORIZED	Source IP not allowlisted.
403	MERCHANT_SERVICE_NOT_CONFIGURED	No integration for the provided service_code + country_code.
404	SUBSCRIPTION_NOT_FOUND	No subscription matches the supplied ID.
500	ERROR	Unexpected server error.

Examples

Request

{
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Success response

{
  "status": "SUCCESS",
  "message": "",
  "status_code": 200,
  "payload": {
    "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "ACTIVE",
    "msisdn": "60123456789",
    "service_code": "NORDVPN",
    "service_name": "NordVPN",
    "subscribed_dt": "2026-04-29T10:15:30.123456",
    "expiry_dt": "2026-05-29T10:15:30.123456",
    "canceled_dt": null,
    "content_link": "https://example.com/content"
  }
}

Failure response

{
  "status": "FAIL",
  "message": "SUBSCRIPTION_NOT_FOUND",
  "status_code": 404
}

Code samples

curl

curl -X POST 'https://merchants.noju.io/subscriptions/status' \
  -H 'Content-Type: application/json' \
  -H "API-KEY: $NOJU_API_KEY" \
  -d '{"subscription_id":"550e8400-e29b-41d4-a716-446655440000"}'

Python

import os
import requests

response = requests.post(
    'https://merchants.noju.io/subscriptions/status',
    headers={
        'Content-Type': 'application/json',
        'API-KEY': os.environ['NOJU_API_KEY'],
    },
    json={
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

if data['status'] == 'SUCCESS':
    print(data['payload'])
else:
    print(f"Failed: {data['message']}")

PHP

<?php
$apiKey = getenv('NOJU_API_KEY');

$payload = json_encode([
    'subscription_id' => '550e8400-e29b-41d4-a716-446655440000',
]);

$ch = curl_init('https://merchants.noju.io/subscriptions/status');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'API-KEY: ' . $apiKey,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$responseBody = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($responseBody, true);

if (($data['status'] ?? null) === 'SUCCESS') {
    var_dump($data['payload']);
} else {
    fwrite(STDERR, 'Failed: ' . ($data['message'] ?? 'unknown') . "\n");
}