telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Subscription Addons

Manage subscription addons.

Get add-on options for subscription

GET/subscriptions/{subscriptionId}/addon-options

Get the add-ons that can be added to this subscription now.

An add-on appears only when its product category matches the subscription's product offering. It must also be part of the customer's product catalog. For example, a travel package will not appear for a cell subscription, because their product categories do not match.

An order that adds an add-on not in this list will be refused.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Responses

200

The add-on options available for this subscription.

application/json

The add-on options available for this subscription.

object

itemsarray of ProductOfferingrequired

The add-on product offerings available for this subscription.

Show child attributes
productOfferingIdstringrequired

Unique identifier for the product offering.

statusenum<string>required

The status of the product offering.

Archived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions.

values

  • AVAILABLE
  • ARCHIVED
namestringrequired

Name of the product offering.

descriptionstring

Description of the product offering.

richContentstring

Rich HTML content with detailed information about the product offering.

uspListarray of string

Short plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.

productobjectrequired

Embedded representation of a product.

Show child attributes
productIdstringrequired

The unique identifier for the product.

internalNamestringrequired

The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.

typeenum<string>required

The type of product offering determines how it can be used and what kind of resource it creates.

SUBSCRIPTION Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).

  • Includes categories like SUBSCRIPTION_CELL, TRAVEL_ESIM
  • Can be created via order or directly depending on configuration
  • Has its own lifecycle (activation, suspension, termination)

SUBSCRIPTION_ADDON Adds features or resources to an existing subscription.

  • Includes categories like TRAVEL_ESIM_PACKAGE
  • Must be attached to a parent subscription

LICENSE Creates a license for business/PBX features.

  • Typically used for enterprise telephony features

EXTERNAL_PRODUCT Represents purchasable items outside the core telecom platform.

  • Can only be ordered via orders, not created directly

SIM_CARD Replaces the SIM card for an existing subscription through a subscription change order.

values

  • SUBSCRIPTION
  • SUBSCRIPTION_ADDON
  • LICENSE
  • EXTERNAL_PRODUCT
  • SIM_CARD
categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
networkProviderIdstring

The unique identifier for the network provider.

featuresobject

The features included with the product, if any. Typically used for telecom products.

Show child attributes
priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

  • ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
  • RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

  • ONE_TIME
  • RECURRING
bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes
customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
addonCategoriesarray of ProductCategory

List of product categories this addon is applicable for. Only populated when type is SUBSCRIPTION_ADDON. For example, a TRAVEL_ESIM_PACKAGE addon might be applicable to TRAVEL_ESIM subscriptions.

internalDescriptionstring

Internal description of the product offering for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/addon-options
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addon-options \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addon-options', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addon-options",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addon-options"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "AVAILABLE",
      "name": "Seamless 10GB",
      "description": "Basic mobile plan with 5GB data and unlimited calls",
      "richContent": "<h3>Features</h3><ul><li>5GB monthly data</li><li>Unlimited calls & texts</li><li>No setup fees</li></ul>",
      "uspList": [
        "5GB of data every month",
        "Unlimited calls and texts",
        "No setup fee"
      ],
      "product": {
        "productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
        "internalName": "us-mobile-unlimited-5gb",
        "type": "SUBSCRIPTION",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "networkProviderId": "tmobile-us",
        "features": {
          "dataMb": 2048,
          "includedCallSeconds": 1000,
          "includedSms": 500,
          "validityDays": 30,
          "countries": [
            "USA",
            "CAN",
            "MEX"
          ],
          "regions": [
            "NORTH_AMERICA"
          ],
          "activationType": "INSTANT",
          "simCardType": "PSIM"
        }
      },
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "customerType": "CONSUMER",
      "addonCategories": [
        "PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
      ],
      "internalDescription": "seamless_cell_10gb_us",
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

List active add-ons for subscription

GET/subscriptions/{subscriptionId}/addons

Get all active and pending add-ons for a subscription.

This endpoint returns only add-ons that are currently attached to the subscription, including their status and scheduling information. Use /addon-options to query available add-ons.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Query parameters

statusarray of SubscriptionAddonStatus

Filter add-ons by status.

Responses

200

Active add-ons for the subscription.

application/json

Active add-ons for the subscription.

object

itemsarray of SubscriptionAddonrequired
Show child attributes
subscriptionAddonIdstringrequired

The unique identifier of the subscription add-on.

subscriptionIdstringrequired

The unique identifier of the subscription this add-on belongs to.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

statusenum<string>required

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

licenseobject

Essential license information without sensitive details.

Show child attributes
licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
assignedToobjectrequired

The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.

Show child attributes
customerobject

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

Show child attributes
activatedAtstringdate-time

When the license was activated.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
scheduledAtstringdate

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

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

expiredAtstringdate-time

The date and time when the add-on expired (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/addons
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "referenceId": "telna-package-12345",
      "productOffering": {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Mobile Unlimited",
        "price": {
          "netPriceMinor": 2999,
          "currency": "USD",
          "priceType": "ONE_TIME",
          "bindingContract": {
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "billingCycle": {
            "period": "MONTHLY",
            "interval": 1
          },
          "currencyOptionsMinor": {
            "propertyName": 1
          }
        },
        "group": {
          "productOfferingGroupId": "mobile-plans",
          "name": "Mobile Plans",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "internalDescription": "Core mobile offerings targeting consumer and business segments"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
      },
      "status": "PENDING",
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "license": {
        "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
        "status": "PENDING",
        "type": "PBX_USER_LEVEL",
        "productOffering": {
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "name": "Mobile Unlimited",
          "price": {
            "netPriceMinor": 2999,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "bindingContract": {
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "source": "STANDARD",
                "invoicingDescription": "Campaign discount"
              }
            },
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "source": "STANDARD",
                "invoicingDescription": "Campaign discount"
              }
            },
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "currencyOptionsMinor": {
              "propertyName": 1
            }
          },
          "group": {
            "productOfferingGroupId": "mobile-plans",
            "name": "Mobile Plans",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "internalDescription": "Core mobile offerings targeting consumer and business segments"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
        },
        "assignedTo": {
          "type": "SUBSCRIPTION",
          "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
          "subscriptionDisplay": "+1 (555) 123-4567"
        },
        "customer": {
          "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
          "name": "John Doe"
        },
        "activatedAt": "2024-01-15T10:30:00Z"
      },
      "pendingStatus": {
        "status": "PENDING",
        "scheduledAt": "2024-02-01"
      },
      "pendingProductOffering": {
        "productOffering": {
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "name": "Mobile Unlimited",
          "price": {
            "netPriceMinor": 2999,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "bindingContract": {
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "source": "STANDARD",
                "invoicingDescription": "Campaign discount"
              }
            },
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "source": "STANDARD",
                "invoicingDescription": "Campaign discount"
              }
            },
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "currencyOptionsMinor": {
              "propertyName": 1
            }
          },
          "group": {
            "productOfferingGroupId": "mobile-plans",
            "name": "Mobile Plans",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "internalDescription": "Core mobile offerings targeting consumer and business segments"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
        },
        "scheduledAt": "2024-02-01"
      },
      "addedAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T09:00:00Z",
      "cancelledAt": "2024-06-30T00:00:00Z",
      "expiredAt": "2024-07-15T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Add subscription add-on

POST/subscriptions/{subscriptionId}/addons

Add an add-on to a subscription.

This endpoint includes adding an add-on to a subscription. The add-on can be scheduled to be activated immediately or at a future date.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyAddAddonRequestrequiredapplication/json

Request to add an add-on to a subscription.

productOfferingIdstringrequired

The unique identifier of the add-on product offering to add. Use the addon-options endpoint to discover which add-ons are available for the subscription.

scheduledAtstringdate

The date when the add-on should be added. If not provided, the add-on will be added immediately or according to the default schedule.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string

Responses

201

Add-on added successfully.

application/json

Add-on added successfully.

objectSubscriptionAddon

An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan.

subscriptionAddonIdstringrequired

The unique identifier of the subscription add-on.

subscriptionIdstringrequired

The unique identifier of the subscription this add-on belongs to.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

  • ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
  • RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

  • ONE_TIME
  • RECURRING
bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes
customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

statusenum<string>required

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

licenseobject

Essential license information without sensitive details.

Show child attributes
licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

assignedToobjectrequired

The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

customerobject

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

activatedAtstringdate-time

When the license was activated.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

scheduledAtstringdate

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

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

expiredAtstringdate-time

The date and time when the add-on expired (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/addons
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "metadata": {
    "propertyName": "string"
  }
}'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productOfferingId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
    scheduledAt: '2024-03-01',
    metadata: {
      propertyName: 'string'
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "scheduledAt": "2024-03-01",
      "metadata": {
        "propertyName": "string"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons"

	payload := strings.NewReader(`{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "telna-package-12345",
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "status": "PENDING",
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "license": {
    "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
    "status": "PENDING",
    "type": "PBX_USER_LEVEL",
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "assignedTo": {
      "type": "SUBSCRIPTION",
      "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
      "subscriptionDisplay": "+1 (555) 123-4567"
    },
    "customer": {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "John Doe"
    },
    "activatedAt": "2024-01-15T10:30:00Z"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "scheduledAt": "2024-02-01"
  },
  "addedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T09:00:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "expiredAt": "2024-07-15T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Cancel subscription add-on

POST/subscriptions/{subscriptionId}/addons/cancel

Cancel an add-on on a subscription.

This endpoint allows cancelling active add-ons on a subscription. The add-on will be canceled according to the specified schedule or immediately if no schedule is provided.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyCancelAddonRequestrequiredapplication/json

Request to cancel an add-on from a subscription.

subscriptionAddonIdstringrequired

The identifier of the subscription add-on to cancel. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_telna-package-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

scheduledAtstringdate

The date when the add-on should be canceled. If not provided, the add-on will be canceled immediately or according to the default schedule.

reasonstring

Free-text explanation of why the add-on is being canceled. Stored with the cancellation for audit and reporting; not shown to the subscriber.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string

Responses

200

Add-on cancellation scheduled successfully.

application/json

Add-on cancellation scheduled successfully.

objectSubscriptionAddon

An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan.

subscriptionAddonIdstringrequired

The unique identifier of the subscription add-on.

subscriptionIdstringrequired

The unique identifier of the subscription this add-on belongs to.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

  • ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
  • RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

  • ONE_TIME
  • RECURRING
bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes
customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

statusenum<string>required

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

licenseobject

Essential license information without sensitive details.

Show child attributes
licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

assignedToobjectrequired

The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

customerobject

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

activatedAtstringdate-time

When the license was activated.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

scheduledAtstringdate

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

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

expiredAtstringdate-time

The date and time when the add-on expired (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/addons/cancel
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "reason": "No longer needed",
  "metadata": {
    "propertyName": "string"
  }
}'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscriptionAddonId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479',
    scheduledAt: '2024-03-01',
    reason: 'No longer needed',
    metadata: {
      propertyName: 'string'
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
      "scheduledAt": "2024-03-01",
      "reason": "No longer needed",
      "metadata": {
        "propertyName": "string"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/cancel"

	payload := strings.NewReader(`{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "reason": "No longer needed",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "telna-package-12345",
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "status": "PENDING",
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "license": {
    "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
    "status": "PENDING",
    "type": "PBX_USER_LEVEL",
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "assignedTo": {
      "type": "SUBSCRIPTION",
      "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
      "subscriptionDisplay": "+1 (555) 123-4567"
    },
    "customer": {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "John Doe"
    },
    "activatedAt": "2024-01-15T10:30:00Z"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "scheduledAt": "2024-02-01"
  },
  "addedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T09:00:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "expiredAt": "2024-07-15T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Change subscription add-on product offering

PUT/subscriptions/{subscriptionId}/addons/product-offering-change

Change an existing add-on to a different product offering (upgrade or downgrade).

This endpoint allows you to change an existing add-on attached to a subscription to a different add-on product offering. The change can be scheduled for immediate or future execution.

When the change takes effect depends on the new product offering chosen, billing cycle, and the preferred schedule date provided in the request.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyChangeAddonRequestrequiredapplication/json

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

subscriptionAddonIdstringrequired

The identifier of the subscription add-on to change. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_telna-package-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

productOfferingIdstringrequired

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

scheduledAtstringdate

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

reasonstring

Free-text explanation of why the add-on is being changed. Stored with the change for audit and reporting; not shown to the subscriber.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string

Responses

200

Add-on change scheduled successfully.

application/json

Add-on change scheduled successfully.

objectSubscriptionAddon

An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan.

subscriptionAddonIdstringrequired

The unique identifier of the subscription add-on.

subscriptionIdstringrequired

The unique identifier of the subscription this add-on belongs to.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

  • ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
  • RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

  • ONE_TIME
  • RECURRING
bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes
customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

statusenum<string>required

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<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.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
internalDescriptionstring

Internal description of the product group for operational use only.

licenseobject

Essential license information without sensitive details.

Show child attributes
licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

assignedToobjectrequired

The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

customerobject

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

activatedAtstringdate-time

When the license was activated.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>

The status of an add-on on a subscription.

  • PENDING: Add-on is scheduled but not yet active
  • ACTIVE: Add-on is currently active and billable
  • CANCELLED: Add-on has been cancelled and is no longer active
  • EXPIRED: Add-on has expired and is no longer active

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

scheduledAtstringdate

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

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

expiredAtstringdate-time

The date and time when the add-on expired (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

PUT /subscriptions/{subscriptionId}/addons/product-offering-change
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-change \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "productOfferingId": "addon-data-5gb",
  "scheduledAt": "2024-02-01",
  "reason": "Customer upgrade request",
  "metadata": {
    "propertyName": "string"
  }
}'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-change', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscriptionAddonId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479',
    productOfferingId: 'addon-data-5gb',
    scheduledAt: '2024-02-01',
    reason: 'Customer upgrade request',
    metadata: {
      propertyName: 'string'
    }
  })
})
requests.put(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-change",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
      "productOfferingId": "addon-data-5gb",
      "scheduledAt": "2024-02-01",
      "reason": "Customer upgrade request",
      "metadata": {
        "propertyName": "string"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-change"

	payload := strings.NewReader(`{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "productOfferingId": "addon-data-5gb",
  "scheduledAt": "2024-02-01",
  "reason": "Customer upgrade request",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "telna-package-12345",
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "status": "PENDING",
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "license": {
    "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
    "status": "PENDING",
    "type": "PBX_USER_LEVEL",
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "assignedTo": {
      "type": "SUBSCRIPTION",
      "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
      "subscriptionDisplay": "+1 (555) 123-4567"
    },
    "customer": {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "John Doe"
    },
    "activatedAt": "2024-01-15T10:30:00Z"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "scheduledAt": "2024-02-01"
  },
  "addedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T09:00:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "expiredAt": "2024-07-15T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get change options for subscription add-on

GET/subscriptions/{subscriptionId}/addons/product-offering-options

Get all available product offerings an existing add-on can be changed to and when the change can take effect.

When the add-on can be changed typically depends on the network setup, billing cycle, and current add-on product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Query parameters

currentProductOfferingIdstringrequired

The current add-on product offering to get change options for.

Responses

200

Available change options for the add-on.

application/json

Available change options for the add-on.

object

itemsarray of ProductOfferingOptionrequired
Show child attributes
productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

changeScheduleenum<string>required

The schedule type for when a product offering change can take effect.

  • INSTANT: Change takes effect immediately
  • FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month
  • NEXT_RENEWAL_DAY: Change takes effect on the next renewal date
  • NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day

values

  • INSTANT
  • FIRST_OF_NEXT_MONTH
  • NEXT_RENEWAL_DAY
  • NEXT_PAYMENT_DAY
changeScheduleDatestringdaterequired

The date when the product offering change can take effect.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/addons/product-offering-options
curl 'https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "currentProductOfferingId": "CURRENT_PRODUCT_OFFERING_ID"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "productOffering": {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Mobile Unlimited",
        "price": {
          "netPriceMinor": 2999,
          "currency": "USD",
          "priceType": "ONE_TIME",
          "bindingContract": {
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "billingCycle": {
            "period": "MONTHLY",
            "interval": 1
          },
          "currencyOptionsMinor": {
            "propertyName": 1
          }
        },
        "group": {
          "productOfferingGroupId": "mobile-plans",
          "name": "Mobile Plans",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "internalDescription": "Core mobile offerings targeting consumer and business segments"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
      },
      "changeSchedule": "INSTANT",
      "changeScheduleDate": "2024-02-01"
    }
  ]
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}