> ## 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. # Add subscription add-on > Add an add-on to a subscription. This endpoint includes adding an add-on to a subscription. The add-on can be scheduled to be activated immediately or at a future date. ## OpenAPI ````yaml /api-reference/bundled_openapi.json post /subscriptions/{subscriptionId}/addons 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: /subscriptions/{subscriptionId}/addons: post: tags: - Subscription Addons summary: Add subscription add-on description: > Add an add-on to a subscription. This endpoint includes adding an add-on to a subscription. The add-on can be scheduled to be activated immediately or at a future date. operationId: addSubscriptionAddon parameters: - in: path name: subscriptionId required: true schema: type: string description: > The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddAddonRequest' responses: '201': description: Add-on added successfully. content: application/json: schema: $ref: '#/components/schemas/SubscriptionAddon' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: parameters: IdempotencyKey: in: header name: X-Idempotency-Key required: false description: > A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. schema: type: string maxLength: 256 schemas: AddAddonRequest: type: object description: Request to add an add-on to a subscription. required: - productOfferingId additionalProperties: false properties: productOfferingId: type: string description: The unique identifier of the add-on product offering to add. scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: >- The date when the add-on should be added. If not provided, the add-on will be added immediately or according to the default schedule. example: '2024-03-01' metadata: $ref: '#/components/schemas/Metadata' SubscriptionAddon: type: object description: An add-on option for a subscription. required: - subscriptionAddonId - subscriptionId - status additionalProperties: false properties: subscriptionAddonId: type: string description: The unique identifier of the subscription add-on. subscriptionId: type: string description: The unique identifier of the subscription this add-on belongs to. referenceId: type: string description: > A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider. example: telna-package-12345 maxLength: 255 productOffering: $ref: '#/components/schemas/EmbeddedProductOffering' status: $ref: '#/components/schemas/SubscriptionAddonStatus' group: $ref: '#/components/schemas/ProductOfferingGroup' license: $ref: '#/components/schemas/EmbeddedLicense' pendingStatus: type: object description: >- Details about when a pending status change is scheduled for this add-on. properties: status: $ref: '#/components/schemas/SubscriptionAddonStatus' scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: The date when the pending status change is scheduled to occur. pendingProductOffering: type: object description: >- Details about the product offering that is scheduled to be applied to this add-on. properties: productOffering: $ref: '#/components/schemas/EmbeddedProductOffering' scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: >- The date when the pending product offering change is scheduled to occur. addedAt: type: string format: date-time description: The date and time when the add-on was added to the subscription. updatedAt: type: string format: date-time description: The date and time when the add-on was last updated. cancelledAt: type: string format: date-time description: The date and time when the add-on was cancelled (if applicable). expiredAt: type: string format: date-time description: The date and time when the add-on expired (if applicable). metadata: $ref: '#/components/schemas/Metadata' 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. EmbeddedProductOffering: type: object description: Embedded representation of a product offering. required: - productOfferingId - name - price properties: productOfferingId: type: string description: The unique identifier for the product offering. name: type: string description: The name of the product offering. price: $ref: '#/components/schemas/Price' group: $ref: '#/components/schemas/ProductOfferingGroup' imageUrl: type: string format: uri description: URL to the image representing the product offering. example: https://cdn.example.com/images/mobile-basic.png SubscriptionAddonStatus: type: string description: | The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active enum: - PENDING - ACTIVE - CANCELLED - EXPIRED 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 EmbeddedLicense: type: object description: Essential license information without sensitive details. required: - licenseId - status - productOffering - assignedTo additionalProperties: false properties: licenseId: type: string description: The unique identifier for the license. example: b3c4d5e6-f7a8-9012-3456-789012345678 status: $ref: '#/components/schemas/LicenseStatus' type: $ref: '#/components/schemas/LicenseType' productOffering: $ref: '#/components/schemas/EmbeddedProductOffering' assignedTo: $ref: '#/components/schemas/EmbeddedAssignedTo' customer: $ref: '#/components/schemas/EmbeddedCustomer' activatedAt: type: string format: date-time description: When the license was activated. example: '2024-01-15T10:30:00Z' 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. 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. 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 LicenseStatus: type: string description: The status of the license. enum: - PENDING - ACTIVE - PAUSED - CANCELLED - BLOCKED LicenseType: type: string description: > The type of license, categorizing the software product or service into various telecommunications license types. EmbeddedAssignedTo: description: > Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. oneOf: - type: object title: Subscription description: License assigned to a subscription required: - type - subscriptionId properties: type: type: string enum: - SUBSCRIPTION description: The type of assignment subscriptionId: type: string description: The unique identifier for the subscription subscriptionDisplay: type: string description: Display name for the subscription (typically the phone number) EmbeddedCustomer: type: object description: >- Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. required: - customerId - name properties: customerId: type: string description: The unique identifier for the customer. name: type: string description: The customer's display name. Any: oneOf: - type: string - type: number - type: boolean - type: object additionalProperties: true - type: array 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 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' Conflict: description: Conflict 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.