telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Product Offerings

Browse product offerings.

List product offerings

GET/product-offerings

List all product offerings available to the customer.

Returns product offerings based on the customer type and access permissions.

Query parameters

typesarray of ProductType

Filter by product offering types.

categoriesarray of ProductCategory

Filter by product offering categories.

customerTypeenum<string>required

Filter by customer type.

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
productCatalogIdstring

Filter by product catalog. Returns only product offerings that belong to the specified catalog. When combined with other filters, all filters are applied together.

includeArchivedbooleandefault false

Whether to include archived product offerings.

countriesarray of string

Filter by country coverage using ISO 3166-1 alpha-3 codes. Returns offerings that provide coverage in any of the specified countries. This includes offerings that have the country explicitly listed or are part of a region that includes the country.

regionsarray of string

Filter by region coverage. Returns offerings that provide coverage in any of the specified regions. Retrieve the available region identifiers from the List Travel eSIM countries endpoint.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of product offerings.

application/json

A list of product offerings.

object

itemsarray of ProductOfferingrequired
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
paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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 /product-offerings
curl 'https://apiv2.example.com/api/v2/product-offerings?customerType=CONSUMER' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/product-offerings?customerType=CONSUMER', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/product-offerings",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "customerType": "CONSUMER"
    }
)
package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/product-offerings?customerType=CONSUMER"

	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": "Mobile plan with 10GB data and unlimited calls and texts",
      "product": {
        "productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
        "internalName": "seamless_cell_10gb_us",
        "type": "SUBSCRIPTION",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "networkProviderId": "tmobile-us",
        "features": {
          "dataMb": 10240,
          "includedCallSeconds": 36000,
          "includedSms": 500
        }
      },
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "RECURRING",
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "standardDiscount": {
          "amountMinor": 500
        },
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 12
          },
          "discount": {
            "amountMinor": 200
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 300
          }
        },
        "currencyOptionsMinor": {
          "USD": 2999,
          "SEK": 29900
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
      },
      "customerType": "BUSINESS",
      "imageUrl": "https://cdn.example.com/images/seamless-10gb.png"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}
{
  "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": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get product offering

GET/product-offerings/{productOfferingId}

Get a product offering by ID.

Path parameters

productOfferingIdstringrequired

The unique identifier of the product offering.

Responses

200

Product offering details.

application/json

Product offering details.

objectProductOffering

A product offering is a product combined with a price that is offered to customers.

The offering's type and category are available via the nested product object. See ProductType and ProductCategory schemas for available values and their meanings.

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
dataMbnumber

Megabytes of data included with the product. Present for cellular, data, and travel eSIM products.

includedCallSecondsinteger

Outbound call seconds included with the product. Present for cellular subscription categories.

includedSmsinteger

Number of SMS messages included with the product. Present for cellular subscription categories.

validityDaysinteger

Number of days the product is valid for. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

countriesarray of string

ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the countries query parameter on list endpoints to filter by coverage.

regionsarray of string

Named regions covered by the product. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the regions query parameter on list endpoints to filter by coverage.

activationTypeenum<string>

How the travel eSIM package activates. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

values

  • INSTANT
  • FIRST_USE
simCardTypeenum<string>

The SIM format for a SIM card product.

values

  • PSIM
  • ESIM
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
durationobjectrequired

A length of time, expressed as a count of some unit.

Show child attributes
discountobject

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
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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
sourceenum<string>

What the customer must do to get the discount:

  • STANDARD is given to every customer who orders the offering.
  • BINDING_CONTRACT needs the customer to commit for the contract's length.
  • UPFRONT_PAYMENT needs the customer to pay for several billing periods at once.

values

  • STANDARD
  • BINDING_CONTRACT
  • UPFRONT_PAYMENT
invoicingDescriptionstring

What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.

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
billingCyclesintegerrequired

How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.

discountobject

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
billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

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
*integerint64
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 /product-offerings/{productOfferingId}
curl https://apiv2.example.com/api/v2/product-offerings/PRODUCT_OFFERING_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/product-offerings/PRODUCT_OFFERING_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/product-offerings/PRODUCT_OFFERING_ID",
    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/product-offerings/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))

}
{
  "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 Travel eSIM countries

GET/product-offerings/countries

List all countries and regions available across travel eSIM product offerings.

Returns a deduplicated list of countries with their names and ISO codes, plus regions that appear on offerings with their constituent country codes.

Query parameters

customerTypeenum<string>required

Filter by customer type.

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

Responses

200

A list of countries and regions available across product offerings.

application/json

A list of countries and regions available across product offerings.

object

countriesarray of objectrequired
Show child attributes
codestringrequired

ISO 3166-1 alpha-3 country code.

namestringrequired

The English name of the country.

regionsarray of objectrequired
Show child attributes
regionstringrequired

The region identifier.

countriesarray of stringrequired

ISO 3166-1 alpha-3 country codes available within this region.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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 /product-offerings/countries
curl 'https://apiv2.example.com/api/v2/product-offerings/countries?customerType=CONSUMER' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/product-offerings/countries?customerType=CONSUMER', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/product-offerings/countries",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "customerType": "CONSUMER"
    }
)
package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/product-offerings/countries?customerType=CONSUMER"

	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))

}
{
  "countries": [
    {
      "code": "USA",
      "name": "United States"
    }
  ],
  "regions": [
    {
      "region": "EUROPE",
      "countries": [
        "SWE",
        "DEU",
        "FRA"
      ]
    }
  ]
}
{
  "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": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}