Skip to main content
PUT
/
subscriptions
/
{subscriptionId}
/
addons
/
product-offering-change
Change subscription add-on product offering
curl --request PUT \
  --url https://apiv2.example.com/subscriptions/{subscriptionId}/addons/product-offering-change \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "subscriptionAddonId": "addon-instance-123",
  "productOfferingId": "addon-data-5gb",
  "scheduledAt": "2024-02-01",
  "reason": "Customer upgrade request",
  "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 change an existing add-on to a different product offering.

​
subscriptionAddonId
string
required

The unique identifier of the subscription addon instance to change.

Example:

"addon-instance-123"

​
productOfferingId
string
required

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

Example:

"addon-data-5gb"

​
scheduledAt
string<date>

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

Example:

"2024-02-01"

​
reason
string

Reason for the change.

Example:

"Customer upgrade request"

​
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 change scheduled 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.