Subscription Addons
The add-ons on a subscription, and the add-ons that the user can buy.
Get add-on options for subscription
/subscriptions/{subscriptionId}/addon-optionsGet 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
subscriptionstringrequiredThe 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
200The add-on options available for this subscription.
application/json
The add-on options available for this subscription.
The add-on options available for this subscription.
object
itemsarray of ProductOfferingrequiredThe add-on product offerings available for this subscription.
Show child attributes
addonarray of ProductCategoryList 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.
broadbandobjectThe values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price.
Show child attributes
additionalnumberrequiredThe amount of data, in GB, that overUsageDataPriceMinor buys. Always 0, because the platform sells no data after the allowance.
earlyintegerint64requiredThe fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee.
monthlyarray of BroadbandFactsFeerequiredThe fees that the provider adds to the monthly price.
Show child attributes
overintegerint64requiredThe price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price.
planstringrequired15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan
identifier on the label is M, then the FCC Registration Number of the brand, then this code.
singlearray of BroadbandFactsFeerequiredThe fees that the customer pays one time, when they buy the plan.
Show child attributes
unlimitedbooleanrequiredTrue when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
descriptionstringDescription of the product offering.
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
internalstringInternal description of the product offering for operational use only.
metadataobject with string keysA 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
*stringnamestringrequiredName of the product offering.
priceobjectrequiredThe 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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA 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
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-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
customobjectBilling 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
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow 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_TIMERECURRING
standardobjectA 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
productobjectrequiredEmbedded representation of a product.
Show child attributes
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
featuresobjectThe features included with the product, if any. Typically used for telecom products.
Show child attributes
internalstringrequiredThe name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.
networkstringThe unique identifier for the network provider.
productstringrequiredThe unique identifier for the product.
typeenum<string>requiredThe 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
SUBSCRIPTIONSUBSCRIPTION_ADDONLICENSEEXTERNAL_PRODUCTSIM_CARD
productstringrequiredUnique identifier for the product offering.
richstringRich HTML content with detailed information about the product offering.
statusenum<string>deprecatedrequiredDeprecated. Use versionStatus instead.
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
AVAILABLEARCHIVED
usparray of stringShort plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.
versionenum<string>requiredThe stage of this version of the product offering.
DRAFT: The brand edits the version. Nobody can order it.TESTING: The brand tests the version. Nobody can order it.PUBLISHED: Each customer can order the version.UNPUBLISHED: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it.ARCHIVED: Nobody can order the version. Existing subscriptions keep it.
values
DRAFTTESTINGPUBLISHEDUNPUBLISHEDARCHIVED
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addon-options \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addon-options', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN'
}
})requests.get(
"https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addon-options",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addon-options"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"addonCategories": [
"PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
],
"broadbandFacts": {
"additionalDataIncrementGb": 0,
"earlyTerminationFeeMinor": 0,
"monthlyProviderFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"overUsageDataPriceMinor": 0,
"planCode": "FLEXSTANDARD001",
"singlePurchaseFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"unlimitedData": false
},
"customerType": "CONSUMER",
"description": "Basic mobile plan with 5GB data and unlimited calls",
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"internalDescription": "seamless_cell_10gb_us",
"metadata": {
"propertyName": "string"
},
"name": "Seamless 10GB",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"product": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"features": {
"activationType": "INSTANT",
"countries": [
"USA",
"CAN",
"MEX"
],
"dataMb": 2048,
"includedCallSeconds": 1000,
"includedSms": 500,
"regions": [
"NORTH_AMERICA"
],
"simCardType": "PSIM",
"validityDays": 30
},
"internalName": "us-mobile-unlimited-5gb",
"networkProviderId": "tmobile-us",
"productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
"type": "SUBSCRIPTION"
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"richContent": "<h3>Features</h3><ul><li>5GB monthly data</li><li>Unlimited calls & texts</li><li>No setup fees</li></ul>",
"status": "AVAILABLE",
"uspList": [
"5GB of data every month",
"Unlimited calls and texts",
"No setup fee"
],
"versionStatus": "PUBLISHED"
}
]
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "not_found",
"hint": "Verify the customerId and try again.",
"message": "The requested customer could not be found."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}List active add-ons for subscription
/subscriptions/{subscriptionId}/addonsGet 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
subscriptionstringrequiredThe 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 SubscriptionAddonStatusFilter add-ons by status.
Responses
200Active add-ons for the subscription.
application/json
Active add-ons for the subscription.
Active add-ons for the subscription.
object
itemsarray of SubscriptionAddonrequiredShow child attributes
addedstringdate-timeThe date and time when the add-on was added to the subscription.
cancelledstringdate-timeThe date and time when the add-on was canceled (if applicable).
expiredstringdate-timeThe date and time when the add-on expired (if applicable).
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
licenseobjectEssential license information without sensitive details.
Show child attributes
activatedstringdate-timeWhen the license was activated.
assignedobjectrequiredThe entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.
Show child attributes
customerobjectCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
licensestringrequiredThe unique identifier for the license.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
statusenum<string>requiredCurrent 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
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringThe 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.
metadataobject with string keysA 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
*stringpendingobjectA 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
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
scheduledstringdateThe date when the pending product offering change is scheduled to occur.
pendingobjectA 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
scheduledstringdateThe date when the pending status change is scheduled to occur.
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
PENDINGACTIVECANCELLEDEXPIRED
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
referencestringmax length 255A 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.
statusenum<string>requiredThe 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
PENDINGACTIVECANCELLEDEXPIRED
subscriptionstringrequiredThe unique identifier of the subscription add-on.
subscriptionstringrequiredThe unique identifier of the subscription this add-on belongs to.
updatedstringdate-timeThe date and time when the add-on was last updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN'
}
})requests.get(
"https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"addedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"expiredAt": "2024-07-15T00:00:00Z",
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"license": {
"activatedAt": "2024-01-15T10:30:00Z",
"assignedTo": {
"subscriptionDisplay": "+1 (555) 123-4567",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"type": "SUBSCRIPTION"
},
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"status": "PENDING",
"type": "PBX_USER_LEVEL"
},
"metadata": {
"propertyName": "string"
},
"pendingProductOffering": {
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"referenceId": "telna-package-12345",
"status": "PENDING",
"subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"updatedAt": "2024-01-20T09:00:00Z"
}
]
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "not_found",
"hint": "Verify the customerId and try again.",
"message": "The requested customer could not be found."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}Get change options for subscription add-on
/subscriptions/{subscriptionId}/addons/product-offering-optionsGet 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
subscriptionstringrequiredThe 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
currentstringrequiredThe current add-on product offering to get change options for.
Responses
200Available change options for the add-on.
application/json
Available change options for the add-on.
Available change options for the add-on.
object
itemsarray of ProductOfferingOptionrequiredShow child attributes
changeenum<string>requiredThe schedule type for when a product offering change can take effect.
- INSTANT: The change takes effect at once
- FIRST_OF_NEXT_MONTH: The change takes effect on the first day of the next calendar month
- NEXT_RENEWAL_DAY: The change takes effect on the next renewal date
- NEXT_PAYMENT_DAY: The change takes effect on the next payment day, when the days already paid for run out
- END_OF_PAID_PERIOD: The change takes effect the day after the current paid period ends
- END_OF_BINDING_PERIOD: The change takes effect the day after the binding period ends
values
INSTANTFIRST_OF_NEXT_MONTHNEXT_RENEWAL_DAYNEXT_PAYMENT_DAYEND_OF_PAID_PERIODEND_OF_BINDING_PERIOD
changestringdaterequiredThe date when the product offering change can take effect.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
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.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
Auth required
Send
X-Api-Key+Bearer JWT
curl 'https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN'
}
})requests.get(
"https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
},
params={
"currentProductOfferingId": "CURRENT_PRODUCT_OFFERING_ID"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"changeSchedule": "INSTANT",
"changeScheduleDate": "2024-02-01",
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}
]
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "not_found",
"hint": "Verify the customerId and try again.",
"message": "The requested customer could not be found."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}