Subscriber Credits and Credit Profiles
Credits play a pivotal role in managing capped subscriber accounts, as they define the data quotas that can be applied to them. Multiple credits can be active on a single subscriber account simultaneously, each tracking its own data-given versus data-used balance. Credits can be configured to automatically renew and expire based on time-based rules, enabling advanced scenarios like data rollover, where unused data from previous credits remains available until it expires. All credit usage is logged to our telemetry backend, ensuring full auditability even after credits are purged. Credits can be managed through Credit Profiles in the UI or added directly via API for external system integration.
How Credits Work
Before diving into configuration, it's important to understand what a credit is and how it behaves throughout its lifecycle.
What is a Credit?
A credit is a data allocation assigned to a capped subscriber account. Each credit:
Has a unique identifier — every credit is tracked individually
Contains a data volume — the amount of data (in gigabits) allocated
Tracks its own balance — how much data was given vs. how much was used
Has an expire date — when the credit reaches its renewal or end date
May have a volume expire date — when the credit's data is no longer available
Has a credit group name — a label used for reporting (e.g., "Monthly Anytime", "TOPUP")
Credit Lifecycle
The diagram below shows the complete lifecycle of a credit from creation to purge:
Key lifecycle events:
Created — Credit is assigned a unique ID and becomes active
Expire Reached — If renew is configured, a NEW credit is created (with its own new ID); if not, the credit is purged
Volume Expire Reached — The credit's data is no longer available; credit is purged
Fully Consumed — All data used; if renew is set, credit waits for renewal; otherwise purged
Purged — Credit removed from active list, but history preserved in telemetry
Key Concepts
Expire — When the credit reaches its renewal point (set by Renew Metric/Span)
Volume Expire — When the credit's data becomes unavailable (set by Volume Metric/Span)
Renewal — Creates a completely NEW credit with a NEW unique ID; the old credit may continue (rollover) or be purged
Rollover — When Volume Expire is greater than Expire, old credits stay active alongside new ones until their volume expires
Usage of Credits
When a subscriber account is capped by its applied service profile, the subscriber will be suspended with the error message "data usage depleted." This can be seen under the Subscriber Account Status. A Subscriber Credit must be added to the Subscriber account before the account is operational.
However, adding a Subscriber Credit requires a Credit Profile, which in turn requires a Credit Group name.
Credit Group Names
The credit group name is the name applied to a credit, such as "Monthly Anytime" or "TOPUP". This name is used to group credits together for reporting purposes.
For example, all credits with the group name "Monthly Anytime" would be reported together, showing combined data usage for "Monthly Anytime" per subscriber.
Subscriber Credit Groups are located at Subscriber Management > Credit Profiles > Credit/Group Names.
Credit Profiles
Credit Profiles are predefined credit templates that can be applied to subscriber accounts.
Credit Profile Name must be unique.
Credit Group name for reporting.
Volume Gb - Data in gigabits provided.
Effective Start and Effective End (Hours)
These fields define the hours of the day (0-23 in UTC) during which a credit is usable. This enables time-of-day based credit allocation.
Example: Day and Night Surfer Credits
A service provider may offer different data packages for day and night usage:
Day Surfer Credit: Effective Start = 06, Effective End = 17 (6am to 5pm UTC)
Night Surfer Credit: Effective Start = 18, Effective End = 05 (6pm to 5am UTC)
A subscriber with both credits applied will use their Day Surfer data during daytime hours and Night Surfer data during nighttime hours.
The effective end is exclusive in the time range.
Volume Metric and Volume Span
The Volume Metric and Volume Span together control how long a credit's data remains available—not how much data is provided (that's the Volume Gb field).
Volume Metric: The unit of time (e.g., Days, Months)
Volume Span: The number of units
Example: Volume Metric = Monthly, Volume Span = 2
If a 10GB credit is added on January 1st with these settings, the credit will expire (and be purged) on March 1st—two months later. Any unused data is lost when the credit expires.
Scenario: Volume Only (No Renew Settings)
When you set Volume Metric and Span but leave Renew Metric and Span empty:
The credit expires after the specified time period
No new credit is automatically created
Remaining unused data is lost when the credit expires
Use case: One-time promotional data, bonus top-ups
Scenario: No Volume Settings
When you leave both Volume Metric and Volume Span empty:
The credit has no time-based expiration
The credit is purged only when all its data is fully consumed
If Renew settings are also empty, this is a one-time credit that lasts until used up
Use case: Pay-as-you-go top-ups, lifetime data packages
Renew Metric and Renew Span
The Renew Metric and Renew Span together control when a new credit is automatically created to replace or supplement the current credit.
Renew Metric: The renewal schedule (e.g., Monthly, 1st of Month, Days)
Renew Span: The number of units between renewals
Example: Renew Metric = Monthly, Renew Span = 1
A credit added on January 15th will automatically create a new credit (with its own unique ID) on February 15th.
Scenario: Renew Only (No Volume Settings)
When you set Renew Metric and Span but leave Volume Metric and Span empty:
The credit's expiration date automatically matches its renewal date
When the credit renews, the old credit is purged and a new credit is created
The new credit has a different ID (it's a completely new credit)
Any unused data from the old credit is lost (no rollover)
Use case: Simple monthly plans where unused data doesn't carry over
Example: 10GB credit, Renew Monthly, Span 1, no Volume settings
January 1st: Credit A created (ID: 1001, 10GB, expires February 1st)
February 1st: Credit A purged, Credit B created with NEW ID: 1002 (10GB, expires March 1st)
March 1st: Credit B purged, Credit C created with NEW ID: 1003 (10GB, expires April 1st)
The Subscriber always has exactly one active credit; each renewal is a distinct credit
Combining Volume and Renew (Rollover)
The most powerful configuration combines both Volume and Renew settings to enable data rollover—where unused data from previous credits remains available.
How Rollover Works
When both settings are configured:
The Renew settings control when new credits are created
The Volume settings control how long each credit's data remains available
If Volume Span > Renew Span, credits overlap, enabling rollover
Example: 10GB credit, Renew Monthly (Span 1), Volume Monthly (Span 2)
January 1st: Credit A created (ID: 1001, 10GB, expires March 1st)
February 1st: Credit A is still active, Credit B is created with NEW ID: 1002 (10GB, expires April 1st)
Subscriber now has 2 active credits (IDs: 1001 and 1002)—unused data from Credit A is still available
March 1st: Credit A (1001) expires and is purged, Credit C created with NEW ID: 1003 (10GB, expires May 1st)
Subscriber has 2 active credits: B (1002, rollover data) and C (1003, new)
This pattern continues, with overlapping credits, so unused data rolls over until its Volume Span expires.
Key Insight: Each credit tracks its own balance independently. Credit A knows it was given 10GB and how much was used. Credit B has its own separate 10GB balance. The system uses the oldest credit data first, maximising the value of rollover data before it expires.
Credit Configuration Quick Reference
The following table summarises common credit configurations and their behaviour:
Volume Settings |
Renew Settings |
Behaviour |
|---|---|---|
None |
None |
Credit lasts until all data is consumed, then purged. No renewal. |
Monthly, Span 1 |
None |
Credit expires after 1 month regardless of remaining data. No renewal. |
None |
Monthly, Span 1 |
Credit expires and renews monthly. Old credit purged, new credit created. No rollover. |
Monthly, Span 2 |
Monthly, Span 1 |
Credit renews monthly but data lasts 2 months. Enables rollover—subscriber has 2 active credits after first renewal. |
Monthly, Span 3 |
Monthly, Span 1 |
Maximum 3 months of rollover. Subscriber can have up to 3 active credits. |
Subscriber Credits
A credit can only be added to capped subscriber accounts.
As per the above view of Subscriber Credits, four credits are currently applied to the Subscriber Account. Two monthly credits are applied using different credit profiles for different time ranges. The first two from the previous month have not yet been purged, and rollover data has been processed per the Volume Metric and Volume Span configured on their profiles. The last two are the most recently applied credits, automatically created based on the previous credits’ credit profile: Renew Metric and Renew Span.
How Credits are Tracked
Unlike traditional systems that maintain a single running balance, our credit system tracks each credit individually. This enables precise auditing and proper rollover accounting that balance-based systems cannot provide.
Per-Credit Balance Tracking
Every credit maintains its own independent record of:
Volume Given: The amount of data allocated to this credit
Volume Used: The amount of data consumed from this credit
Volume Remaining: Calculated as Given minus Used
When a subscriber uses data, the system deducts from the oldest active credit first. This ensures rollover data is used before it expires, maximising value for the subscriber.
Credit Chain Tracking
When a credit renews, the system creates a new credit with a new unique ID. To maintain the relationship between credits in a renewal chain, the system tracks the original credit's ID in a group ID field on all subsequent credits.
Example:
Credit A (ID: 1001) is the original credit, group_id = 1001
Credit B (ID: 1002) renews from A, group_id = 1001
Credit C (ID: 1003) renews from B, group_id = 1001
This chain tracking enables:
Reporting on all credits derived from an original subscription
Auditing the complete history of a subscriber's data allocations
Understanding rollover patterns over time
Telemetry and Historical Data
All credit usage is logged to our telemetry backend in real-time. This includes:
Every data usage event is attributed to a specific credit
Credit creation, renewal, and expiration events
Balance snapshots at regular intervals
This architecture enables:
Complete audit trails for billing disputes
Historical usage reports per credit, per subscriber, or per credit group
Accurate rollover analysis showing how much data was carried over vs. lost
Compliance reporting with full data lineage
Adding Credits via API
Typical Workflow (UI)
When adding a credit to a subscriber through the user interface, you select a Credit Profile—a pre-configured template that defines the credit's parameters (data volume, effective hours, volume/renew settings, etc.). The Credit Profile acts as a reusable template, ensuring consistency and reducing manual configuration errors when allocating credits to subscribers.
This is the recommended approach for most use cases, as Credit Profiles can be managed centrally and applied consistently across many subscribers.
Direct API Integration
For external systems such as billing platforms, provisioning systems, or custom portals, we provide an API that allows credits to be added directly to subscriber accounts without requiring a Credit Profile.
When using the API, you specify all credit parameters directly in the request:
Data volume (in gigabits)
Effective start and end hours
Volume metric and span (expiration rules)
Renew metric and span (renewal rules)
Credit group name (for reporting) — optional, see below
This enables:
Integration with external billing systems that manage their own credit logic
Automated provisioning workflows
Custom credit allocations that don't fit standard Credit Profile templates
Real-time credit adjustments based on external business events
Automatic Credit Naming
When using the direct API (/v1/topup endpoints), the credit group name is optional. If you do not provide a name, the system automatically generates one based on the credit's configuration:
Renewal-based names:
Monthly renewal (renew_metric=months, renew_span=1) → "Monthly"
1st-of-month renewal (renew_metric=1st-of-month, renew_span=1) → "Monthly"
Other recurring credits → "{span} {metric} recurring" (e.g., "2 months recurring")
Time slot suffix:
The system appends a time slot based on start_hour and end_hour:
All-day (00:00 to 23:59) → "Anytime"
Daytime hours → "Daytime"
Nighttime hours → "Nighttime"
Custom hours → "{start}-{end}" (e.g., "06:00-18:00")
Non-recurring credits:
Credits without renewal settings receive the prefix "TOPUP" (e.g., "TOPUP Anytime").
Examples of auto-generated names:
Monthly renewal, all-day → "Monthly Anytime"
Monthly renewal, night hours → "Monthly Nighttime"
2-month recurring, all-day → "2 months recurring Anytime"
No renewal, all-day → "TOPUP Anytime"