Subscriber Credits API

Overview

This API provides programmatic access to manage subscriber credits. For a complete understanding of how credits work, including lifecycle, expiration, and renewal behaviour, see the Subscriber Credits and Credit Profiles documentation.

API Integrity and Deduplication

The external_id field provides idempotency for credit creation:

A unique identifier for the subscriber in an external system
Correlates subscribers between Nebula and external systems
Must be unique per subscriber
Prevents duplicate credits when retrying failed requests
Returns 409 Conflict if a credit with the same external_id already exists
Can be used to look up credits without storing internal credit IDs

Upgrading and Downgrading Credits

Since the platform supports multiple active credits per subscriber, upgrading or downgrading is achieved by adding a new credit and removing the existing one.

Each credit tracks its own data balance independently. Removing an existing credit without proper handling may result in loss of remaining data balance.

Recommended approach: Use replace_credit_id or replace_external_id when creating the new credit. This performs an atomic operation that:

Creates the new credit
Purges the specified existing credit
Copies data usage from the old credit to the new credit

This ensures data integrity and continuity of service.

Understanding Multiple Active Credits

Multiple credits can be active simultaneously on a subscriber account. This is by design to support rollover scenarios where volume expiration exceeds the renewal date.

To filter for current (non-rolled-over) credits only, use the query parameter ?rolled_over=false when listing credits.

Credit Profiles and Subscriber Credits

These APIs manage Credit Profiles and apply them to Subscribers. This is the standard approach for credit management via the UI and API.

See Subscriber Credits and Credit Profiles for detailed documentation.

Credit Group Names

Define at least one credit group name before creating credit profiles.

See Credit Group Names.

GET

/v1/credit/names

(subscriber)

List Credit Names.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
id	query	string	Filter by id. (can suffix with wildcard )*
l	query	integer	Paginate Limit / Entities per Page. (1-50, -1 for streaming)
name	query	string	Filter by name. (can suffix with wildcard )*
p	query	integer	Paginate Current Page. (default 1)
sc	query	string	Sort by Property/Column. (id, name)
sd	query	string	Sort direction. asc for Ascending or desc for Descending

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
id	body	string	Unique Entity ID.
metadata.page	body	integer	Current Page. (always 1 for infinite)
metadata.pages	body	integer	Total Pages. (always 1 for infinite)
metadata.per_page	body	integer	Equeal to the entities per page limit or always equal to total records for infinite queries.
metadata.records	body	integer	Total entities found. (always max 250 unless infinite is accepted query parameter)
name	body	string	Name of Entity.

Response Example

{
    "payload": [
        {
            "id": "95ca692a-9ecb-4f72-b375-8024e4314d97",
            "name": "ANYTIME DATA"
        },
        {
            "id": "802adac9-4d4b-4f0e-ab95-73d8d80b7d35",
            "name": "MONTHLY ANYTIME"
        },
        {
            "id": "76a02416-bb5d-11ee-8769-525400bd8e3a",
            "name": "Monthly Daytime"
        },
        {
            "id": "9690e530-bb5c-11ee-8769-525400bd8e3a",
            "name": "TOPUP Anytime"
        },
        {
            "id": "1d00f8f3-bb5e-11ee-8769-525400bd8e3a",
            "name": "TOPUP Daytime"
        }
    ],
    "metadata": {
        "records": 5,
        "page": 1,
        "pages": 1,
        "per_page": 10
    }
}

GET

/v1/credit/name/{credit_group_name_id}

(subscriber)

Get credit name by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_group_name_id	url	string	Credit Group Name Id.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.

Response Example

{
    "id": "9690e530-bb5c-11ee-8769-525400bd8e3a",
    "name": "TOPUP Anytime"
}

POST

/v1/credit/name

(subscriber)

Add credit name.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
name	body	string	Name of Entity.	X

Request Example

{
    "name": "TOPUP Anytime"
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.

Response Example

{
    "id": "9690e530-bb5c-11ee-8769-525400bd8e3a",
    "name": "TOPUP Anytime"
}

PATCH

/v1/credit/name/{credit_group_name_id}

(subscriber)

Update credit group name by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_group_name_id	url	string	Credit Group Name Id.	X
name	body	string	Name of Entity.

Request Example

{
    "name": "TOPUP Anytime"
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.

Response Example

{
    "id": "9690e530-bb5c-11ee-8769-525400bd8e3a",
    "name": "TOPUP Anytime"
}

DELETE

/v1/credit/name/{credit_group_name_id}

(subscriber)

Remove credit group name by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
credit_group_name_id	url	string	Credit Group Name Id.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Credit Profiles

Define at least one credit profile before applying credits to subscribers.

See Credit Profiles.

GET

/v1/credit/profiles

(subscriber)

List Credit Profiles.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_name	query	string	Filter by credit_name. (can suffix with wildcard )*
id	query	string	Filter by id. (can suffix with wildcard )*
l	query	integer	Paginate Limit / Entities per Page. (1-50, -1 for streaming)
name	query	string	Filter by name. (can suffix with wildcard )*
p	query	integer	Paginate Current Page. (default 1)
sc	query	string	Sort by Property/Column. (id, name, volume_gb, credit_name)
sd	query	string	Sort direction. asc for Ascending or desc for Descending
volume_gb	query	string	Filter by volume_gb. (can suffix with wildcard )*

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_name	body	string	Credit Name.
end_hour	body	string	End Hour.
id	body	string	Unique Entity ID.
metadata.page	body	integer	Current Page. (always 1 for infinite)
metadata.pages	body	integer	Total Pages. (always 1 for infinite)
metadata.per_page	body	integer	Equeal to the entities per page limit or always equal to total records for infinite queries.
metadata.records	body	integer	Total entities found. (always max 250 unless infinite is accepted query parameter)
name	body	string	Name of Entity.
renew_metric	body	string	Renew Metric.
renew_span	body	integer	Renew Span.
start_hour	body	string	Start Hour.
volume_gb	body	integer	Volume Gb.
volume_metric	body	string	Volume Metric.
volume_span	body	integer	Volume Span.

Response Example

{
    "payload": [
        {
            "id": "7a68ba0f-0782-483b-bf39-93955b2e4852",
            "name": "123GB Monthly Anytime",
            "credit_name": "Monthly Anytime",
            "start_hour": "00:00",
            "end_hour": "23:59",
            "volume_gb": 123,
            "volume_metric": "months",
            "volume_span": 2,
            "renew_metric": "1st-of-month",
            "renew_span": 1
        }
    ],
    "metadata": {
        "records": 1,
        "page": 1,
        "pages": 1,
        "per_page": 10
    }
}

GET

/v1/credit/profile/{credit_profile_id}

(subscriber)

View credit profile by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_profile_id	url	string	Credit Profile Id.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_name	body	string	Credit Name.
end_hour	body	string	End Hour.
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.
renew_metric	body	string	Renew Metric.
renew_span	body	integer	Renew Span.
start_hour	body	string	Start Hour.
volume_gb	body	integer	Volume Gb.
volume_metric	body	string	Volume Metric.
volume_span	body	integer	Volume Span.

Response Example

{
    "id": "7a68ba0f-0782-483b-bf39-93955b2e4852",
    "name": "123GB Monthly Anytime",
    "credit_name": "Monthly Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "volume_gb": 123,
    "volume_metric": "months",
    "volume_span": 2,
    "renew_metric": "1st-of-month",
    "renew_span": 1
}

POST

/v1/credit/profile

(subscriber)

Add credit profile.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_name	body	string	Credit Name.	X
end_hour	body	string	End Hour.	X
name	body	string	Name of Entity.	X
renew_metric	body	string	Renew Metric.	X
renew_span	body	integer	Renew Span.	X
start_hour	body	string	Start Hour.	X
volume_gb	body	integer	Volume Gb.	X
volume_metric	body	string	Volume Metric.	X
volume_span	body	integer	Volume Span.	X

Request Example

{
    "name": "123GB Monthly Anytime",
    "credit_name": "Monthly Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "volume_gb": 123,
    "volume_metric": "months",
    "volume_span": 2,
    "renew_metric": "1st-of-month",
    "renew_span": 1
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_name	body	string	Credit Name.
end_hour	body	string	End Hour.
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.
renew_metric	body	string	Renew Metric.
renew_span	body	integer	Renew Span.
start_hour	body	string	Start Hour.
volume_gb	body	integer	Volume Gb.
volume_metric	body	string	Volume Metric.
volume_span	body	integer	Volume Span.

Response Example

{
    "id": "7a68ba0f-0782-483b-bf39-93955b2e4852",
    "name": "123GB Monthly Anytime",
    "credit_name": "Monthly Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "volume_gb": 123,
    "volume_metric": "months",
    "volume_span": 2,
    "renew_metric": "1st-of-month",
    "renew_span": 1
}

PATCH

/v1/credit/profile/{credit_profile_id}

(subscriber)

Update credit profile by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_profile_id	url	string	Credit Profile Id.	X
credit_name	body	string	Credit Name.
end_hour	body	string	End Hour.
name	body	string	Name of Entity.
renew_metric	body	string	Renew Metric.
renew_span	body	integer	Renew Span.
start_hour	body	string	Start Hour.
volume_gb	body	integer	Volume Gb.
volume_metric	body	string	Volume Metric.
volume_span	body	integer	Volume Span.

Request Example

{
    "credit_name": "Monthly Daytime",
    "volume_gb": 123,
    "start_hour": "06:00",
    "end_hour": "17:00",
    "volume_metric": "months",
    "volume_span": 2,
    "renew_metric": "1st-of-month",
    "renew_span": 1
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_name	body	string	Credit Name.
end_hour	body	string	End Hour.
id	body	string	Unique Entity ID.
name	body	string	Name of Entity.
renew_metric	body	string	Renew Metric.
renew_span	body	integer	Renew Span.
start_hour	body	string	Start Hour.
volume_gb	body	integer	Volume Gb.
volume_metric	body	string	Volume Metric.
volume_span	body	integer	Volume Span.

Response Example

{
    "id": "7a68ba0f-0782-483b-bf39-93955b2e4852",
    "credit_name": "Monthly Daytime",
    "volume_gb": 123,
    "start_hour": "06:00",
    "end_hour": "17:00",
    "volume_metric": "months",
    "volume_span": 2,
    "renew_metric": "1st-of-month",
    "renew_span": 1
}

DELETE

/v1/credit/profile/{credit_profile_id}

(subscriber)

Remove credit profile by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
credit_profile_id	url	string	Credit Profile Id.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Subscriber Credits

Apply credits to subscribers using predefined credit profiles, or purge existing credits.

See Subscriber Credits.

GET

/v1/credits/{subscriber_id}

(subscriber)

List Credits for a subscriber.

Service
subscriber

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Subscriber Id.	X
external_id	query	string	Filter by external_id. (can suffix with wildcard )*
group_id	query	string	Filter by group_id. (can suffix with wildcard )*
id	query	string	Filter by id. (can suffix with wildcard )*
l	query	integer	Paginate Limit / Entities per Page. (1-50, -1 for streaming)
name	query	string	Filter by name. (can suffix with wildcard )*
p	query	integer	Paginate Current Page. (default 1)
rolled_over	query	boolean	Filter by rolled_over.
sc	query	string	Sort by Property/Column. (expire, volume_expire)
sd	query	string	Sort direction. asc for Ascending or desc for Descending
volume_gb	query	integer	Filter by volume_gb.

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_profile	body	string	Credit Profile.
credit_profile_id	body	string	Credit Profile Id.
end_hour	body	string	End Hour.
expire	body	string	Expire.
id	body	string	Unique Entity ID.
left_over_gb	body	integer	Left Over Gb.
metadata.page	body	integer	Current Page. (always 1 for infinite)
metadata.pages	body	integer	Total Pages. (always 1 for infinite)
metadata.per_page	body	integer	Equeal to the entities per page limit or always equal to total records for infinite queries.
metadata.records	body	integer	Total entities found. (always max 250 unless infinite is accepted query parameter)
name	body	string	Name of Entity.
start_hour	body	string	Start Hour.
subscriber_id	body	string	Subscriber Id.
used	body	integer	Used.
used_bytes	body	integer	Used Bytes.
used_gb	body	integer	Used Gb.
username	body	string	Username.
volume_expire	body	string	Volume Expire.
volume_gb	body	integer	Volume Gb.

Response Example

{
    "payload": [
        {
            "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
            "credit_profile_id": "64ea15cd-e432-4a98-bcf3-511a00182945",
            "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
            "volume_gb": 123,
            "name": "TOPUP Anytime",
            "start_hour": "00:00",
            "end_hour": "23:59",
            "expire": null,
            "volume_expire": "2024-04-15T10:02:20+00:00",
            "used": 0,
            "username": "test@example.com",
            "used_bytes": 0,
            "used_gb": 0.0,
            "left_over_gb": 123.0,
            "credit_profile": "123GB TOPUP Anytime"
        }
    ],
    "metadata": {
        "records": 1,
        "page": 1,
        "pages": 1,
        "per_page": 10
    }
}

GET

/v1/credit/{subscriber_credit_id}

(subscriber)

Show subscriber credit by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_credit_id	url	string	Subscriber Credit Id.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_profile	body	string	Credit Profile.
credit_profile_id	body	string	Credit Profile Id.
end_hour	body	string	End Hour.
expire	body	string	Expire.
id	body	string	Unique Entity ID.
left_over_gb	body	integer	Left Over Gb.
name	body	string	Name of Entity.
start_hour	body	string	Start Hour.
subscriber_id	body	string	Subscriber Id.
used	body	integer	Used.
used_bytes	body	integer	Used Bytes.
used_gb	body	integer	Used Gb.
username	body	string	Username.
volume_expire	body	string	Volume Expire.
volume_gb	body	integer	Volume Gb.

Response Example

{
    "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
    "credit_profile_id": "64ea15cd-e432-4a98-bcf3-511a00182945",
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
    "volume_gb": 123,
    "name": "TOPUP Daytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "expire": null,
    "volume_expire": "2024-04-15T10:02:20+00:00",
    "used": 0,
    "username": "test7000",
    "used_bytes": 0,
    "used_gb": 0.0,
    "left_over_gb": 123.0,
    "credit_profile": "123GB TOPUP Daytime"
}

POST

/v1/credit

(subscriber)

Add credit to subscriber.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credit_profile_id	body	string	Credit Profile Id.
subscriber_id	body	string	Subscriber Id.

Request Example

{
    "credit_profile_id": "64ea15cd-e432-4a98-bcf3-511a00182945",
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d"
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
credit_profile	body	string	Credit Profile.
credit_profile_id	body	string	Credit Profile Id.
end_hour	body	string	End Hour.
expire	body	string	Expire.
id	body	string	Unique Entity ID.
left_over_gb	body	integer	Left Over Gb.
name	body	string	Name of Entity.
start_hour	body	string	Start Hour.
subscriber_id	body	string	Subscriber Id.
used	body	integer	Used.
used_bytes	body	integer	Used Bytes.
used_gb	body	integer	Used Gb.
username	body	string	Username.
volume_expire	body	string	Volume Expire.
volume_gb	body	integer	Volume Gb.

Response Example

{
    "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
    "credit_profile_id": "64ea15cd-e432-4a98-bcf3-511a00182945",
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
    "volume_gb": 123,
    "name": "TOPUP Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "expire": null,
    "volume_expire": "2024-04-15T10:02:20+00:00",
    "used": 0,
    "username": "test@example.com",
    "used_bytes": 0,
    "used_gb": 0.0,
    "left_over_gb": 123.0,
    "credit_profile": "123GB TOPUP Anytime"
}

DELETE

/v1/credit/{subscriber_credit_id}

(subscriber)

Remove subscriber credit by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
subscriber_credit_id	url	string	Subscriber Credit Id.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Raw Subscriber Credits API

Provision credits directly without using credit profiles. This API is designed for external billing systems and provisioning platforms that manage their own credit logic.

Warning

Credit Names and Reporting

The name field is optional—do not specify it unless you fully understand the implications. When omitted, the system automatically generates a consistent name based on the credit's renewal settings and effective hours (e.g., "Monthly Anytime", "TOPUP Nighttime").

Credit group names are used to aggregate usage data in subscriber reports. All credits with the same name appear together in reports, enabling comparison across subscribers and time periods. If you provide a custom name that differs from existing names—even from previously auto-generated names—the usage data will be tracked separately, fragmenting your reports.

Example: If existing credits use "Monthly Anytime" (auto-generated) and you create new credits with "monthly-anytime" or "Monthly_Anytime", these will appear as separate entries in reports, making it impossible to see combined usage.

This API bypasses credit profile validation. Your external system must handle renewal scheduling, expiration logic, and credit lifecycle management.

GET

/v1/topups/{subscriber_id}

(subscriber)

List credits for a subscriber.

Service
subscriber

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Subscriber ID to list credits for.	X
external_id	query	string	Filter by external_id. (can suffix with wildcard )*
group_id	query	string	Filter by group_id. (can suffix with wildcard )*
id	query	string	Filter by id. (can suffix with wildcard )*
l	query	integer	Paginate Limit / Entities per Page. (1-50, -1 for streaming)
name	query	string	Filter by name. (can suffix with wildcard )*
p	query	integer	Paginate Current Page. (default 1)
rolled_over	query	boolean	Filter by rolled_over.
sc	query	string	Sort by Property/Column. (expire, volume_expire)
sd	query	string	Sort direction. asc for Ascending or desc for Descending
volume_gb	query	integer	Filter by volume_gb.

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
end_hour	body	string	Effective end hour (UTC).
expire	body	string	Credit expiration datetime (renewal date).
external_id	body	string	External system identifier.
group_id	body	string	Links renewed credits to their original credit.
id	body	string	Unique credit identifier.
left_over_gb	body	string	Remaining data in gigabits. Currently returned as a string; future v2 API will return as number.
metadata.page	body	integer	Current Page. (always 1 for infinite)
metadata.pages	body	integer	Total Pages. (always 1 for infinite)
metadata.per_page	body	integer	Equeal to the entities per page limit or always equal to total records for infinite queries.
metadata.records	body	integer	Total entities found. (always max 250 unless infinite is accepted query parameter)
name	body	string	Credit group name.
start_hour	body	string	Effective start hour (UTC).
subscriber_id	body	string	Subscriber ID the credit belongs to.
used_bytes	body	integer	Data used in bytes.
used_gb	body	string	Data used in gigabits. Currently returned as a string; future v2 API will return as number.
username	body	string	Subscriber username.
volume_expire	body	string	Volume expiration datetime (when data becomes unavailable).
volume_gb	body	integer	Data volume in gigabits.

Response Example

{
    "payload": [
        {
            "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
            "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
            "volume_gb": 50,
            "name": "Monthly Anytime",
            "start_hour": "00:00",
            "end_hour": "23:59",
            "expire": "2024-03-01T00:00:00+00:00",
            "volume_expire": "2024-04-01T00:00:00+00:00",
            "used_bytes": 5000000000,
            "used_gb": "5.0",
            "left_over_gb": "45.0",
            "username": "user@example.com",
            "external_id": "EXT-12345",
            "group_id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16"
        }
    ],
    "metadata": {
        "records": 1,
        "page": 1,
        "pages": 1,
        "per_page": 10
    }
}

GET

/v1/topup/{id}

(subscriber)

Get credit by ID.

Service
subscriber

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
id	url	string	Credit ID to retrieve.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
end_hour	body	string	Effective end hour (UTC).
expire	body	string	Credit expiration datetime (renewal date).
external_id	body	string	External system identifier.
group_id	body	string	Links renewed credits to their original credit.
id	body	string	Unique credit identifier.
left_over_gb	body	string	Remaining data in gigabits. Currently returned as a string; future v2 API will return as number.
name	body	string	Credit group name.
start_hour	body	string	Effective start hour (UTC).
subscriber_id	body	string	Subscriber ID the credit belongs to.
used_bytes	body	integer	Data used in bytes.
used_gb	body	string	Data used in gigabits. Currently returned as a string; future v2 API will return as number.
username	body	string	Subscriber username.
volume_expire	body	string	Volume expiration datetime (when data becomes unavailable).
volume_gb	body	integer	Data volume in gigabits.

Response Example

{
    "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
    "volume_gb": 50,
    "name": "Monthly Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "expire": "2024-03-01T00:00:00+00:00",
    "volume_expire": "2024-04-01T00:00:00+00:00",
    "used_bytes": 5000000000,
    "used_gb": "5.0",
    "left_over_gb": "45.0",
    "username": "user@example.com",
    "external_id": "EXT-12345",
    "group_id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16"
}

POST

/v1/topup

(subscriber)

Add credit to subscriber.

Service
subscriber

Add a credit directly to a subscriber without using a credit profile.
This endpoint allows external systems to provision credits with full
control over all credit parameters.

If external_id is provided and already exists for the subscriber,
a 409 Conflict error is returned to prevent duplicates.

Use replace_credit_id or replace_external_id to atomically replace
an existing credit (useful for upgrades/downgrades).

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
end_hour	body	string	Effective end hour in UTC (default "00:00").
expire	body	string	Explicit expiration datetime (ISO 8601 format).
external_id	body	string	External system identifier for deduplication.
name	body	string	Credit group name for reporting. Do not specify unless you fully understand the implications. If omitted, the system automatically generates a name based on the credit configuration: - Monthly renewal (renew_metric=months, renew_span=1) generates "Monthly Anytime", "Monthly Daytime", or "Monthly Nighttime" - 1st-of-month renewal generates the same naming pattern - Other recurring credits generate "{span} {metric} recurring {time_slot}" (e.g., "2 months recurring Anytime") - Non-recurring credits generate "TOPUP Anytime", "TOPUP Daytime", or "TOPUP Nighttime" The time slot suffix (Anytime, Daytime, Nighttime) is determined by start_hour and end_hour. WARNING: Credit group names are used for aggregate reporting across all subscribers. If you provide a custom name that differs from existing names, even from previously auto-generated names like "Monthly Anytime", usage data will be tracked separately in reports. This fragments your reporting data. Only specify a custom name if you are intentionally creating a new reporting category.
notify_at	body	string	Notification thresholds as comma-separated percentages (default "100,90,80,70,50").
renew_metric	body	string	Renewal metric (months, days, 1st-of-month).
renew_span	body	integer	Number of units for renewal interval.
replace_credit_id	body	string	Credit ID to replace (for upgrades/downgrades).
replace_external_id	body	string	External ID of credit to replace.
start_hour	body	string	Effective start hour in UTC (default "00:00").
subscriber_id	body	string	Subscriber ID to add credit to.	X
volume_gb	body	integer	Data volume in gigabits.	X
volume_metric	body	string	Volume expiration metric (months, days).
volume_span	body	integer	Number of units for volume expiration.

Request Example

{
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
    "volume_gb": 50,
    "name": "Monthly Anytime",
    "external_id": "EXT-12345",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "renew_metric": "1st-of-month",
    "renew_span": 1,
    "volume_metric": "months",
    "volume_span": 2
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
end_hour	body	string	Effective end hour (UTC).
expire	body	string	Credit expiration datetime (renewal date).
external_id	body	string	External system identifier.
group_id	body	string	Links renewed credits to their original credit.
id	body	string	Unique credit identifier.
left_over_gb	body	string	Remaining data in gigabits. Currently returned as a string; future v2 API will return as number.
name	body	string	Credit group name.
start_hour	body	string	Effective start hour (UTC).
subscriber_id	body	string	Subscriber ID the credit belongs to.
used_bytes	body	integer	Data used in bytes.
used_gb	body	string	Data used in gigabits. Currently returned as a string; future v2 API will return as number.
username	body	string	Subscriber username.
volume_expire	body	string	Volume expiration datetime (when data becomes unavailable).
volume_gb	body	integer	Data volume in gigabits.

Response Example

{
    "id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16",
    "subscriber_id": "2c621ccc-c9dd-11ee-b885-ddbef08e6d9d",
    "volume_gb": 50,
    "name": "Monthly Anytime",
    "start_hour": "00:00",
    "end_hour": "23:59",
    "expire": "2024-03-01T00:00:00+00:00",
    "volume_expire": "2024-04-01T00:00:00+00:00",
    "used_bytes": 0,
    "used_gb": "0.0",
    "left_over_gb": "50.0",
    "username": "user@example.com",
    "external_id": "EXT-12345",
    "group_id": "4ed4495c-cbe9-11ee-9127-a5b2efd1bd16"
}

DELETE

/v1/topup/{id}

(subscriber)

Delete credit by ID.

Service
subscriber

Purges a credit from the subscriber account. Historical data is preserved in telemetry.

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
id	url	string	Credit ID to delete.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

DELETE

/v1/topup/group/{group_id}

(subscriber)

Delete credits by group ID.

Service
subscriber

Purges all credits in a renewal chain by their group ID.
The group ID links all credits that originated from the same initial credit.
Historical data is preserved in telemetry.

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
group_id	url	string	Group ID of the credit chain to delete.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

DELETE

/v1/topup/by_external_id/{subscriber_id}/{external_id}

(subscriber)

Delete credit by external ID.

Service
subscriber

Purges a credit using its external ID and subscriber ID.
Useful for external systems that track credits by their own identifiers.
Historical data is preserved in telemetry.

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
external_id	url	string	External system identifier of the credit to delete.	X
subscriber_id	url	string	Subscriber ID the credit belongs to.	X

Response Status Codes

Code	Meaning
204	OK - No Content
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable