Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Product Catalogs

Browse product catalogs.

List product catalogs

GET/product-catalogs

List all product catalogs with optional text search filtering and pagination.

Product catalogs define curated sets of product offerings for specific contexts such as customer segments, regions, or sales channels.

Query parameters

filterstring

Filter by catalog name or ID prefix.

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

application/json

A list of product catalogs.

object

itemsarray of ProductCatalogListItemrequired
Show child attributes
productCatalogIdstringrequired

Unique identifier for the product catalog.

namestringrequired

Name of the product catalog.

descriptionstring

Description of the product catalog.

extendsDefaultbooleanrequired

Whether this catalog extends the default product catalog. When true, the catalog inherits all offerings from the default catalog in addition to its own.

isDefaultboolean

Whether this is the default catalog for its customer type. A customer with no catalog of their own is served the default one.

customerTypeenum<string>

The kind of customer this catalog serves. Absent on catalogs that have not been assigned a 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
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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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

	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": [
    {
      "productCatalogId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "US Consumer Catalog",
      "description": "Product catalog for US consumer customers",
      "extendsDefault": true,
      "isDefault": true,
      "customerType": "CONSUMER"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "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."
}

Get storefront

GET/storefront

Get the product catalogs that a storefront sells from, and the sections that the storefront shows their product offerings in.

The caller decides the answer:

  • A request with customerType gets the default catalogs for that customer type. Every visitor who did not choose a customer sees these catalogs.
  • A request with customerId gets the catalogs of that customer. The request must carry the bearer token of a signed-in user who can order for the customer.

A customer with no catalog of its own gets the default catalogs. A customer whose catalogs are all for the other customer type gets no catalog. A catalog that extends the default catalog comes after the default catalog.

The sections are in display order: by catalog, then in the order that each catalog arranges them. A catalog that extends the default catalog puts its own product offerings into sections of the default catalog. An empty list of sections means that nobody arranged these catalogs.

The sections are only the layout. initialProductOfferingIds names the initial product offerings of the catalogs, and a section holds only such product offerings. productOfferings gives the details of each product offering that the catalogs sell to the caller.

simTypes names the SIM types that the storefront sells. They are the same for every customer.

Query parameters

customerTypeenum<string>

The kind of customer to get the catalogs for. It is necessary unless you send customerId. You cannot send it together with customerId, because the customer has a type of its own.

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
customerIdstring

The customer to get the catalogs for. The request must carry the bearer token of a signed-in user who can order for this customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Responses

200

The storefront.

application/json

The storefront.

objectStorefront

The product catalogs that a storefront sells from, and the sections that it shows their product offerings in.

customerTypeenum<string>required

The kind of customer that these catalogs sell to.

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
productCatalogIdsarray of stringrequired

The product catalogs that the storefront sells from. Empty when no catalog applies.

sectionsarray of ProductCatalogSectionrequired

The sections of these catalogs, in display order. A section gives only initial product offerings.

Show child attributes
productCatalogSectionIdstringrequired

Unique identifier for the section.

namestringrequired

The heading of the section.

descriptionstring

The text under the heading. Absent when the section has none.

productOfferingIdsarray of stringrequired

The product offerings in the section, in display order.

initialProductOfferingIdsarray of string

The initial product offerings of these catalogs. A customer can order them as a new subscription or as an external product. A storefront with no sections shows these product offerings.

productOfferingsarray of ProductOfferingrequired

The product offerings that these catalogs sell to the caller. A section names its product offerings by their ID, and this list gives their details. A customer with the TestAndTrainingEntity tag gets the newest TESTING version of a product offering in place of the version that the catalog holds.

Show child attributes
productOfferingIdstringrequired

Unique identifier for the product offering.

statusenum<string>deprecatedrequired

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

  • AVAILABLE
  • ARCHIVED
versionStatusenum<string>required

The 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

  • DRAFT
  • TESTING
  • PUBLISHED
  • UNPUBLISHED
  • 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_CELL_FIXED - Cellular subscription at a fixed location
  • 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
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

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
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number 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

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_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_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
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. When includesTax is true, this amount is the total the customer pays, and the tax is a part of it.

includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

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_CELL_FIXED - Cellular subscription at a fixed location
  • 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
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

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
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number 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

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_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_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
internalDescriptionstring

Internal description of the product group for operational use only.

variantSetIdstring

The variant set that the product offering belongs to. A variant set holds the product offerings that are price variants of one plan, for example one plan with 0, 12 and 24 months of binding. Absent when the product offering is not in a variant set.

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
broadbandFactsobject

The 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
planCodestringrequired

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

monthlyProviderFeesarray of BroadbandFactsFeerequired

The fees that the provider adds to the monthly price.

Show child attributes
singlePurchaseFeesarray of BroadbandFactsFeerequired

The fees that the customer pays one time, when they buy the plan.

Show child attributes
earlyTerminationFeeMinorintegerint64required

The fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee.

overUsageDataPriceMinorintegerint64required

The price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price.

additionalDataIncrementGbnumberrequired

The amount of data, in GB, that overUsageDataPriceMinor buys. Always 0, because the platform sells no data after the allowance.

unlimitedDatabooleanrequired

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

simTypesarray of SimType

The SIM types that the storefront sells with a new subscription. A subscription line with another SIM type cannot go through the checkout of the storefront. Empty when the storefront sells no SIM type.

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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. Branch on reason, 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 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.

reasonstring

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

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

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

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.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

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

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

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

}
{
  "customerType": "CONSUMER",
  "productCatalogIds": [
    "string"
  ],
  "sections": [
    {
      "productCatalogSectionId": "0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90",
      "name": "Mobile plans",
      "description": "Plans with unlimited calls and texts",
      "productOfferingIds": [
        "string"
      ]
    }
  ],
  "initialProductOfferingIds": [
    "string"
  ],
  "productOfferings": [
    {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "AVAILABLE",
      "versionStatus": "PUBLISHED",
      "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,
          "unlimitedData": false,
          "includedCallSeconds": 1000,
          "includedSms": 500,
          "validityDays": 30,
          "countries": [
            "USA",
            "CAN",
            "MEX"
          ],
          "regions": [
            "NORTH_AMERICA"
          ],
          "activationType": "INSTANT",
          "simCardType": "PSIM"
        }
      },
      "price": {
        "netPriceMinor": 2999,
        "includesTax": false,
        "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"
      },
      "variantSetId": "8c2d4e6f-1a3b-4c5d-9e7f-0a1b2c3d4e5f",
      "customerType": "CONSUMER",
      "addonCategories": [
        "PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
      ],
      "internalDescription": "seamless_cell_10gb_us",
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "metadata": {
        "propertyName": "string"
      },
      "broadbandFacts": {
        "planCode": "FLEXSTANDARD001",
        "monthlyProviderFees": [
          {
            "name": "Federal Universal Service Fund",
            "amountMinor": 21
          }
        ],
        "singlePurchaseFees": [
          {
            "name": "Federal Universal Service Fund",
            "amountMinor": 21
          }
        ],
        "earlyTerminationFeeMinor": 0,
        "overUsageDataPriceMinor": 0,
        "additionalDataIncrementGb": 0,
        "unlimitedData": false
      }
    }
  ],
  "simTypes": [
    "PHYSICAL"
  ]
}
{
  "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."
}