> ## Documentation Index
> Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# List product offerings
> List all product offerings available to the customer.
Returns product offerings based on the customer type and access permissions.
## OpenAPI
````yaml /api-reference/bundled_openapi.json get /product-offerings
openapi: 3.1.0
info:
title: Telness Tech Connect
version: 2.0.0-alpha
description: >
Telness Tech Connect API provides all you need to own your user's
connectivity experience.
Go back to [Telnesstech.com](https://telnesstech.com)
servers:
- url: https://apiv2.example.com
description: Connect API URL for your domain
security:
- apiKey: []
- bearerAuth: []
apiKey: []
tags:
- name: Auth
description: Authenticate users and obtain access tokens.
- name: Users
description: Manage users.
- name: Customers
description: Manage customers.
- name: Subscriptions
description: Manage subscriptions and subscription.
- name: Subscription Addons
description: Manage subscription addons.
- name: Subscription Usage
description: Get subscription usage.
- name: Subscribers
description: Manage subscribers.
- name: Licenses
description: Manage licenses.
- name: Product Offerings
description: Browse product offerings.
- name: Product Catalogs
description: Browse product catalogs.
- name: Product Discounts
description: Discounts and promotions.
- name: Orders
description: Manage orders and line items.
- name: Payment Intents
description: >-
Inspect payment intents, the money collected over card rails for orders
and renewals.
- name: Payment Links
description: Create and manage payment links for orders and invoices.
- name: Payment Sessions
description: Create and manage payment sessions for orders.
- name: Payment Profiles
description: Manage customer payment profiles and methods.
- name: Payment Profile Sessions
description: Create sessions for setting up payment profiles.
- name: Signing sessions
description: Handle contract signing sessions for postpaid orders.
- name: Porting
description: Manage number porting for subscriptions.
- name: Taxes
description: Calculate taxes for products and line items.
- name: Invoices
description: Manage invoices and invoice items.
- name: Tools
description: >-
Tools for address validation, number porting, device info, and network
coverage.
- name: Inventory
description: Manage phone number inventory, SIM cards, and reservations.
- name: Workflows
description: Dynamic processing of customer journeys and events.
paths:
/product-offerings:
get:
tags:
- Product Offerings
summary: List product offerings
description: >
List all product offerings available to the customer.
Returns product offerings based on the customer type and access
permissions.
operationId: listProductOfferings
parameters:
- in: query
name: types
schema:
type: array
items:
$ref: '#/components/schemas/ProductType'
description: Filter by product offering types.
- in: query
name: categories
schema:
type: array
items:
$ref: '#/components/schemas/ProductCategory'
description: Filter by product offering categories.
- in: query
name: customerType
required: true
schema:
$ref: '#/components/schemas/CustomerType'
description: Filter by customer type.
- in: query
name: productCatalogId
schema:
type: string
description: >
Filter by product catalog. Returns only product offerings that
belong to the specified catalog.
When combined with other filters, all filters are applied together.
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
- in: query
name: includeArchived
schema:
type: boolean
default: false
description: Whether to include archived product offerings.
- in: query
name: promoCode
schema:
type: string
description: Apply promotional pricing by providing a valid promo code.
example: STUDENT2024
- in: query
name: countries
schema:
type: array
items:
type: string
description: >
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.
example:
- USA
- CAN
- MEX
- in: query
name: regions
schema:
type: array
items:
type: string
description: >
Filter by region coverage.
Returns offerings that provide coverage in any of the specified
regions.
Valid regions include: EUROPE, AMERICAS, ASIA_PACIFIC, GLOBAL,
NORTH_AMERICA, SOUTH_AMERICA, AFRICA, MIDDLE_EAST.
example:
- EUROPE
- NORTH_AMERICA
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A list of product offerings.
content:
application/json:
schema:
type: object
required:
- items
- pagination
properties:
items:
type: array
items:
$ref: '#/components/schemas/ProductOffering'
pagination:
$ref: '#/components/schemas/Pagination'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
ProductType:
type: string
description: >
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
enum:
- SUBSCRIPTION
- SUBSCRIPTION_ADDON
- LICENSE
- EXTERNAL_PRODUCT
example: SUBSCRIPTION
ProductCategory:
type: string
description: >
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
enum:
- 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
example: PRODUCT_CATEGORY_SUBSCRIPTION_CELL
CustomerType:
type: string
description: The type of customer.
enum:
- CONSUMER
- BUSINESS
ProductOffering:
type: object
description: >
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.
required:
- productOfferingId
- status
- name
- price
- customerType
- product
additionalProperties: false
properties:
productOfferingId:
type: string
description: Unique identifier for the product offering.
status:
type: string
enum:
- AVAILABLE
- ARCHIVED
description: >
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.
example: AVAILABLE
name:
type: string
description: Name of the product offering.
example: Seamless 10GB
description:
type: string
description: Description of the product offering.
example: Basic mobile plan with 5GB data and unlimited calls
richContent:
type: string
description: >-
Rich HTML content with detailed information about the product
offering.
example: >-
Features
- 5GB monthly data
- Unlimited calls &
texts
- No setup fees
product:
$ref: '#/components/schemas/EmbeddedProduct'
price:
$ref: '#/components/schemas/Price'
group:
$ref: '#/components/schemas/ProductOfferingGroup'
customerType:
$ref: '#/components/schemas/CustomerType'
addonCategories:
type: array
items:
$ref: '#/components/schemas/ProductCategory'
description: >
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.
internalDescription:
type: string
description: >-
Internal description of the product offering for operational use
only.
example: seamless_cell_10gb_us
imageUrl:
type: string
format: uri
description: URL to the image representing the product offering.
example: https://cdn.example.com/images/mobile-basic.png
metadata:
$ref: '#/components/schemas/Metadata'
Pagination:
type: object
additionalProperties: false
properties:
nextCursor:
type: string
nullable: true
description: Opaque token for fetching the next page. Null when no more results.
EmbeddedProduct:
type: object
description: Embedded representation of a product.
required:
- productId
- internalName
- type
- category
properties:
productId:
type: string
description: The unique identifier for the product.
internalName:
type: string
description: The internal name of the product.
type:
$ref: '#/components/schemas/ProductType'
category:
$ref: '#/components/schemas/ProductCategory'
networkProviderId:
type: string
description: The unique identifier for the network provider.
example: tmobile-us
features:
type: object
description: >-
The features included with the product, if any. Typically used for
telecom products.
properties:
dataMb:
type: number
description: |
Megabytes of data included with the product.
Present for cellular, data, and travel eSIM products.
example: 2048
includedCallSeconds:
type: integer
description: |
Outbound call seconds included with the product.
Present for cellular subscription categories.
example: 1000
includedSms:
type: integer
description: |
Number of SMS messages included with the product.
Present for cellular subscription categories.
example: 500
validityDays:
type: integer
description: |
Number of days the product is valid for.
Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).
example: 30
countries:
type: array
items:
type: string
description: >
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.
example:
- USA
- CAN
- MEX
regions:
type: array
items:
type: string
description: >
Named regions covered by the product (e.g., EUROPE, AMERICAS,
ASIA_PACIFIC, GLOBAL).
Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).
Use the `regions` query parameter on list endpoints to filter by
coverage.
example:
- NORTH_AMERICA
activationType:
type: string
description: |
How the travel eSIM package activates.
Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).
enum:
- INSTANT
- FIRST_USE
example: INSTANT
Price:
type: object
description: Pricing information with discount details.
required:
- cost
- basePrice
- currency
- period
- priceType
properties:
discount:
type: number
format: decimal
description: The discount amount from the original price.
example: 5
netPrice:
type: number
format: decimal
description: The final cost after all discounts are applied.
example: 5
currency:
type: string
description: The currency code.
example: USD
priceType:
$ref: '#/components/schemas/PriceType'
boundMonths:
type: integer
description: The number of months the price is bound to (for recurring prices).
example: 12
billingCycle:
$ref: '#/components/schemas/BillingCycle'
currencyOptions:
type: object
additionalProperties:
type: number
format: decimal
description: >-
Per-currency price overrides keyed by three-letter ISO currency code
(e.g. "USD", "SEK"). Each value is the cost in that currency.
ProductOfferingGroup:
type: object
description: A product group organizes related product offerings.
required:
- productOfferingGroupId
- name
- category
additionalProperties: false
properties:
productOfferingGroupId:
type: string
description: Unique identifier for the product group.
example: mobile-plans
name:
type: string
description: Name of the product group in the requested locale.
example: Mobile Plans
description:
type: string
description: Description of the product group in the requested locale.
example: >-
Bundled cell subscriptions with unlimited calls and SMS with ILD
enabled.
category:
$ref: '#/components/schemas/ProductCategory'
internalDescription:
type: string
description: Internal description of the product group for operational use only.
example: Core mobile offerings targeting consumer and business segments
Metadata:
type: object
additionalProperties:
type: string
description: >
A set of key-value pairs that can be attached to an object for storing
additional information in a semi-structured format.
Error:
type: object
required:
- message
- code
properties:
message:
type: string
description: A human-readable message providing more details about the error.
code:
type: string
description: A machine-readable code for the error.
details:
type: array
description: Additional details about the error.
items:
type: object
required:
- message
- code
properties:
message:
type: string
description: >-
A human-readable message providing more details about the
error.
code:
type: string
description: A machine-readable code for the specific detail.
property:
type: string
description: The property or field related to the error.
suggestion:
$ref: '#/components/schemas/Any'
description: >
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.
hint:
type: string
description: A hint to help resolve the error.
PriceType:
type: string
description: The type of pricing model applied to the product offering.
enum:
- ONE_TIME
- RECURRING
BillingCycle:
type: object
description: The billing cycle for recurring prices.
required:
- period
- interval
properties:
period:
type: string
description: The billing period.
enum:
- MONTHLY
interval:
type: integer
description: The interval of the billing period.
example: 1
Any:
oneOf:
- type: string
- type: number
- type: boolean
- type: object
additionalProperties: true
- type: array
parameters:
Limit:
in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
description: The maximum number of items to return.
Cursor:
in: query
name: cursor
schema:
type: string
description: Opaque pagination token from a previous response's nextCursor.
responses:
BadRequest:
description: The request was malformed or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication is required to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Access to this resource is forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too many requests have been sent in a given amount of time.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalServerError:
description: An unexpected error occurred on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-Api-Key
description: >
An API key that grants access to the Connect API. You can create and
manage API keys in the portal.
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Bearer authentication with JWT tokens is used to authenticate users.
Do note that a valid API keys is also required to access the Connect API
to prove that requests are made by a trusted party.
Requests with a JWT token is scoped to the permissions of the user the
token belongs to, regardless of the API key used.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.