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": {}
}
'

import requests

url = "https://apiv2.example.com/subscriptions/{subscriptionId}/addons"

payload = {
    "productOfferingId": "<string>",
    "scheduledAt": "2024-03-01",
    "metadata": {}
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({productOfferingId: '<string>', scheduledAt: '2024-03-01', metadata: {}})
};

fetch('https://apiv2.example.com/subscriptions/{subscriptionId}/addons', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apiv2.example.com/subscriptions/{subscriptionId}/addons",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productOfferingId' => '<string>',
    'scheduledAt' => '2024-03-01',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apiv2.example.com/subscriptions/{subscriptionId}/addons"

	payload := strings.NewReader("{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apiv2.example.com/subscriptions/{subscriptionId}/addons")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apiv2.example.com/subscriptions/{subscriptionId}/addons")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "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"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "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"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "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": {}
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

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": {}
}
'

import requests

url = "https://apiv2.example.com/subscriptions/{subscriptionId}/addons"

payload = {
    "productOfferingId": "<string>",
    "scheduledAt": "2024-03-01",
    "metadata": {}
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({productOfferingId: '<string>', scheduledAt: '2024-03-01', metadata: {}})
};

fetch('https://apiv2.example.com/subscriptions/{subscriptionId}/addons', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apiv2.example.com/subscriptions/{subscriptionId}/addons",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productOfferingId' => '<string>',
    'scheduledAt' => '2024-03-01',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apiv2.example.com/subscriptions/{subscriptionId}/addons"

	payload := strings.NewReader("{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apiv2.example.com/subscriptions/{subscriptionId}/addons")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apiv2.example.com/subscriptions/{subscriptionId}/addons")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productOfferingId\": \"<string>\",\n  \"scheduledAt\": \"2024-03-01\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "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"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "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"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "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": {}
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": [
    {
      "message": "<string>",
      "code": "<string>",
      "property": "<string>",
      "suggestion": "<string>"
    }
  ],
  "hint": "<string>"
}

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.

Show child attributes

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.

Show child attributes

group

object

A product group organizes related product offerings.

Show child attributes

license

object

Essential license information without sensitive details.

Show child attributes

pendingStatus

object

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

Show child attributes

pendingProductOffering

object

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

Show child attributes

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.

Show child attributes

Getting started

Guides

Overview

API reference

Add subscription add-on

Authorizations

Headers

Path Parameters

Body

Response