utility.md

Utility Module

Preview operations for subscription changes (dry run). Useful for showing customers what will happen before they confirm.

Access: sdk.utility

Methods

previewTopup

Preview a topup operation without making changes.

previewTopup(params: PreviewTopupParams): Promise<PreviewTopupResponse>

Input: PreviewTopupParams

Field	Type	Required	Description
subscription_id	string	Yes	Subscription ID to preview topup for
package_id	string	Yes	Topup package ID
quantity	number	No	Number of topup units (default: 1)

Output: PreviewTopupResponse

Field	Type	Description
before	SubscriptionState	Current subscription state
after	SubscriptionState	Projected state after topup
topup_summary	TopupSummary	Summary of changes

TopupSummary:

Field	Type	Description
data_to_add	number	Data to add in bytes
data_to_add_formatted	string	Formatted data (e.g., "5GB")
days_to_add	number	Days to add to expiry

Example:

const preview = await sdk.utility.previewTopup({
  subscription_id: "sub_123",
  package_id: "pkg_topup_5gb",
  quantity: 2,
});

console.log(`Current data: ${preview.before.data_remaining_formatted}`);
console.log(`After topup: ${preview.after.data_remaining_formatted}`);
console.log(`Data added: ${preview.topup_summary.data_to_add_formatted}`);

---

previewPackageChange

Preview a package change operation without making changes.

previewPackageChange(params: PreviewPackageChangeParams): Promise<PreviewPackageChangeResponse>

Input: PreviewPackageChangeParams

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
package_id	string	Yes	New package ID to change to

Output: PreviewPackageChangeResponse

Field	Type	Description
current_subscription	SubscriptionState	Current subscription details
new_package	PackageDetails	New package details
transition_type	string	Type: "upgrade", "downgrade", or "change"
carryover	CarryoverDetails	Data/time carryover rules
after	SubscriptionState	Projected state after change

CarryoverDetails:

Field	Type	Description
data_carried	number	Data carried over in bytes
data_carried_formatted	string	Formatted (e.g., "2.5GB")
data_forfeited	number	Data forfeited in bytes
data_forfeited_formatted	string	Formatted
rule_applied	string	Carryover rule applied

Example:

const preview = await sdk.utility.previewPackageChange({
  customer_id: "ispcust_123",
  package_id: "pkg_premium_50mbps",
});

console.log(`Transition: ${preview.transition_type}`);
console.log(`Data carried: ${preview.carryover.data_carried_formatted}`);
console.log(`Data forfeited: ${preview.carryover.data_forfeited_formatted}`);
console.log(`New allocation: ${preview.after.data_total_allocation_formatted}`);

---

previewRenewal

Preview a subscription renewal without making changes.

previewRenewal(params: PreviewRenewalParams): Promise<PreviewRenewalResponse>

Input: PreviewRenewalParams

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
quantity	number	No	Number of renewal units (default: 1)

Output: PreviewRenewalResponse

Field	Type	Description
current_subscription	SubscriptionState	Current subscription
renewal_package	PackageDetails	Package to renew with
renewal_summary	RenewalSummary	Summary of what will happen
projected_subscription	SubscriptionState	Projected state

RenewalSummary:

Field	Type	Description
will_activate_immediately	boolean	Whether renewal activates now
will_queue	boolean	Whether items will be queued
items_to_queue	number	Number of items to queue
reason	string	Reason for queueing

Example:

const preview = await sdk.utility.previewRenewal({
  customer_id: "ispcust_123",
  quantity: 2,
});

if (preview.renewal_summary.will_queue) {
  console.log(`${preview.renewal_summary.items_to_queue} items will be queued`);
  console.log(`Reason: ${preview.renewal_summary.reason}`);
} else {
  console.log("Renewal will activate immediately");
}

console.log(`New expiry: ${preview.projected_subscription.expiry_date}`);