Product Catalogs
The product catalogs that a storefront sells from, for the customer that the user orders for.
Get storefront
/storefrontGet 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
customerTypegets the default catalogs for that customer type. Every visitor who did not choose a customer sees these catalogs. - A request with
customerIdgets 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.
simTypes names the SIM types that the storefront sells. They are the same for every customer.
Query parameters
customerenum<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
CONSUMERBUSINESS
customerstringThe 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
200The storefront.
application/json
The storefront.
The storefront.
objectStorefront
The product catalogs that a storefront sells from, and the sections that it shows their product offerings in.
customerenum<string>requiredThe 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
CONSUMERBUSINESS
initialarray of stringThe 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.
productarray of stringrequiredThe product catalogs that the storefront sells from. Empty when no catalog applies.
sectionsarray of ProductCatalogSectionrequiredThe sections of these catalogs, in display order. A section gives only initial product offerings.
Show child attributes
descriptionstringThe text under the heading. Absent when the section has none.
namestringrequiredThe heading of the section.
productstringrequiredUnique identifier for the section.
productarray of stringrequiredThe product offerings in the section, in display order.
simarray of SimTypeThe 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.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too 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.
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.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/storefront \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'fetch('https://apiv2.example.com/api/v2/end-user/storefront', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN'
}
})requests.get(
"https://apiv2.example.com/api/v2/end-user/storefront",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/storefront"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"customerType": "CONSUMER",
"initialProductOfferingIds": [
"string"
],
"productCatalogIds": [
"string"
],
"sections": [
{
"description": "Plans with unlimited calls and texts",
"name": "Mobile plans",
"productCatalogSectionId": "0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90",
"productOfferingIds": [
"string"
]
}
],
"simTypes": [
"PHYSICAL"
]
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "not_found",
"hint": "Verify the customerId and try again.",
"message": "The requested customer could not be found."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}