Skip to main content
POST
/
subscriptions
/
{subscriptionId}
/
addons
Add subscription add-on
curl --request POST \
  --url https://apiv2.example.com/subscriptions/{subscriptionId}/addons \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "productOfferingId": "<string>",
  "scheduledAt": "2024-03-01",
  "metadata": {}
}
'
{
  "subscriptionAddonId": "<string>",
  "subscriptionId": "<string>",
  "status": "PENDING",
  "referenceId": "telna-package-12345",
  "productOffering": {
    "productOfferingId": "<string>",
    "name": "<string>",
    "price": {
      "currency": "USD",
      "priceType": "ONE_TIME",
      "discount": 5,
      "netPrice": 5,
      "boundMonths": 12,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {}
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    }
  },
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "license": {
    "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
    "status": "PENDING",
    "productOffering": {
      "productOfferingId": "<string>",
      "name": "<string>",
      "price": {
        "currency": "USD",
        "priceType": "ONE_TIME",
        "discount": 5,
        "netPrice": 5,
        "boundMonths": 12,
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {}
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      }
    },
    "assignedTo": {
      "type": "SUBSCRIPTION",
      "subscriptionId": "<string>",
      "subscriptionDisplay": "<string>"
    },
    "type": "<string>",
    "customer": {
      "customerId": "<string>",
      "name": "<string>"
    },
    "activatedAt": "2024-01-15T10:30:00Z"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2023-12-25"
  },
  "pendingProductOffering": {
    "productOffering": {
      "productOfferingId": "<string>",
      "name": "<string>",
      "price": {
        "currency": "USD",
        "priceType": "ONE_TIME",
        "discount": 5,
        "netPrice": 5,
        "boundMonths": 12,
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {}
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      }
    },
    "scheduledAt": "2023-12-25"
  },
  "addedAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "cancelledAt": "2023-11-07T05:31:56Z",
  "expiredAt": "2023-11-07T05:31:56Z",
  "metadata": {}
}

Authorizations

​
X-Api-Key
string
header
required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

​
X-Idempotency-Key
string

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.

Maximum string length: 256

Path Parameters

​
subscriptionId
string
required

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.

Body

application/json

Request to add an add-on to a subscription.

​
productOfferingId
string
required

The unique identifier of the add-on product offering to add.

​
scheduledAt
string<date>

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
object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Response

Add-on added successfully.

An add-on option for a subscription.

​
subscriptionAddonId
string
required

The unique identifier of the subscription add-on.

​
subscriptionId
string
required

The unique identifier of the subscription this add-on belongs to.

​
status
enum<string>
required

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
Available options:
PENDING,
ACTIVE,
CANCELLED,
EXPIRED
​
referenceId
string

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.

Maximum string length: 255
Example:

"telna-package-12345"

​
productOffering
object

Embedded representation of a product offering.

​
group
object

A product group organizes related product offerings.

​
license
object

Essential license information without sensitive details.

​
pendingStatus
object

Details about when a pending status change is scheduled for this add-on.

​
pendingProductOffering
object

Details about the product offering that is scheduled to be applied to this add-on.

​
addedAt
string<date-time>

The date and time when the add-on was added to the subscription.

​
updatedAt
string<date-time>

The date and time when the add-on was last updated.

​
cancelledAt
string<date-time>

The date and time when the add-on was cancelled (if applicable).

​
expiredAt
string<date-time>

The date and time when the add-on expired (if applicable).

​
metadata
object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.