Change subscription add-on product offering

Authorizations

X-Api-Key

string

header

required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

X-Idempotency-Key

string

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Maximum string length: 256

Path Parameters

subscriptionId

string

required

The unique identifier of the subscription.

Body

application/json

Request to change an existing add-on to a different product offering.

productOfferingId

string

required

The unique identifier of the new add-on product offering to change to.

Example:

"addon-data-5gb"

scheduledAt

string<date>

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

Example:

"2024-02-01"

reason

string

Reason for the change.

Example:

"Customer upgrade request"

metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

metadata.{key}

string

Response

Add-on change scheduled successfully.

A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.

subscriptionId

string

required

The unique identifier for the subscription.

status

enum<string>

required

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED

type

string

required

The type of subscription, categorizing the service into various telecommunications service types.

display

string

required

The display name for the subscription, typically a pretty-print of the msisdn.

msisdn

string

required

The currently active phone number for this subscription.

customer

object

required

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes

customer.customerId

string

required

The unique identifier for the customer.

customer.name

string

required

The customer's display name.

productOffering

object

required

Embedded representation of a product offering.

Show child attributes

productOffering.productOfferingId

string

required

The unique identifier for the product offering.

productOffering.name

string

required

The name of the product offering.

productOffering.price

object

required

Pricing information with discount details.

Show child attributes

productOffering.price.currency

string

required

The currency code.

Example:

"USD"

productOffering.price.discount

number<decimal>

default:5

The discount amount from the original price.

productOffering.price.netPrice

number<decimal>

The final cost after all discounts are applied.

Example:

5

productOffering.price.priceType

enum<string>

The type of pricing model applied to the product offering.

Available options:

ONE_TIME,

RECURRING

productOffering.price.boundMonths

integer

The number of months the price is bound to (for recurring prices).

Example:

12

productOffering.price.billingCycle

object

The billing cycle for recurring prices.

Show child attributes

productOffering.price.billingCycle.period

enum<string>

The billing period.

Available options:

MONTHLY

productOffering.price.billingCycle.interval

integer

The interval of the billing period.

Example:

1

productOffering.productOfferingGroupId

string

The unique identifier for the product offering group.

productOffering.group

object

Product offering group information embedded in responses.

Show child attributes

productOffering.group.productOfferingGroupId

string

required

The unique identifier for the product offering group.

productOffering.group.name

string

required

The name of the product offering group.

productOffering.group.category

string

required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Example:

"SUBSCRIPTION_CELL"

sim

object

required

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes

sim.esim

boolean

required

Indicates whether the subscription uses eSIM technology.

sim.imei

string

International Mobile Equipment Identity, uniquely identifying the mobile device.

Only applicable for eSIM.

sim.iccid

string

Integrated Circuit Card identifier, uniquely identifying the SIM card.

activatedAt

string<date-time>

required

The date and time when the subscription was activated.

createdAt

string<date-time>

required

The date and time when the subscription was created.

updatedAt

string<date-time>

required

The date and time when the subscription was last updated.

subscriber

object

A subscriber is a user that has a subscription.

Show child attributes

subscriber.subscriberId

string

required

The unique identifier of the subscriber.

subscriber.name

string

required

The name of the subscriber.

subscriber.email

string<email>

Optional email address of the subscriber.

subscriber.address

object

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

Show child attributes

subscriber.address.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

subscriber.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

subscriber.address.zip

string

required

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

Example:

"01701"

subscriber.address.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

subscriber.address.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

subscriber.address.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

subscriber.address.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

subscriber.address.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

subscriber.createdAt

string<date-time>

Date and time when the subscriber was created.

subscriber.updatedAt

string<date-time>

Date and time when the subscriber was last updated.

extensions

object

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

extensions.{key}

string

pendingMsisdn

object

Details about when a pending phone number change is scheduled for this subscription.

Show child attributes

pendingMsisdn.msisdn

string

The pending phone number for this subscription, if a number change is scheduled.

pendingMsisdn.scheduledAt

string<date>

The date when the pending change (e.g., number change) is scheduled to occur.

pendingStatus

object

Details about when a pending status change is scheduled for this subscription.

Show child attributes

pendingStatus.status

enum<string>

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED

pendingStatus.scheduledAt

string<date>

The date when the pending status change is scheduled to occur.

pendingProductOffering

object

Pending product offering change.

Show child attributes

pendingProductOffering.scheduledAt

string<date>

required

The date when the pending product offering change is scheduled to occur.

pendingProductOffering.product

object

required

Embedded representation of a product offering.

Show child attributes

pendingProductOffering.product.productOfferingId

string

required

The unique identifier for the product offering.

pendingProductOffering.product.name

string

required

The name of the product offering.

pendingProductOffering.product.price

object

required

Pricing information with discount details.

Show child attributes

pendingProductOffering.product.price.currency

string

required

The currency code.

Example:

"USD"

pendingProductOffering.product.price.discount

number<decimal>

default:5

The discount amount from the original price.

pendingProductOffering.product.price.netPrice

number<decimal>

The final cost after all discounts are applied.

Example:

5

pendingProductOffering.product.price.priceType

enum<string>

The type of pricing model applied to the product offering.

Available options:

ONE_TIME,

RECURRING

pendingProductOffering.product.price.boundMonths

integer

The number of months the price is bound to (for recurring prices).

Example:

12

pendingProductOffering.product.price.billingCycle

object

The billing cycle for recurring prices.

Show child attributes

pendingProductOffering.product.price.billingCycle.period

enum<string>

The billing period.

Available options:

MONTHLY

pendingProductOffering.product.price.billingCycle.interval

integer

The interval of the billing period.

Example:

1

pendingProductOffering.product.productOfferingGroupId

string

The unique identifier for the product offering group.

pendingProductOffering.product.group

object

Product offering group information embedded in responses.

Show child attributes

pendingProductOffering.product.group.productOfferingGroupId

string

required

The unique identifier for the product offering group.

pendingProductOffering.product.group.name

string

required

The name of the product offering group.

pendingProductOffering.product.group.category

string

required

A product category is a sub-type for grouping offerings of the same type.

Example:

"SUBSCRIPTION_CELL"

porting

object

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

Show child attributes

porting.msisdn

string

required

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

porting.status

enum<string>

required

Current status of the porting process.

Available options:

PENDING,

IN_PROGRESS,

SCHEDULED,

COMPLETED,

FAILED

porting.direction

enum<string>

required

The direction of the number porting, either inbound (to us) or outbound (from us).

Available options:

INBOUND,

OUTBOUND

porting.scheduledAt

string<date>

required

The date when the number porting is scheduled to occur.

cancelledAt

string<date-time>

The date and time when the subscription was cancelled (if applicable).

metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

metadata.{key}

string

Getting started

Overview

API reference

Change subscription add-on product offering

Authorizations

Headers

Path Parameters

Body

Response