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",
  "productOffering": {
    "productOfferingId": "<string>",
    "name": "<string>",
    "price": {
      "currency": "USD",
      "priceType": "ONE_TIME",
      "discount": 5,
      "netPrice": 5,
      "boundMonths": 12,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "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": "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
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "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
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "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",
  "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 unique identifier of the subscription.

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
Available options:
PENDING,
ACTIVE,
CANCELLED
​
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).¨

​
metadata
object

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