Add Bundle

📦 Basic Plan

✅ Usage Scenario

Subscribe a data plan for a SIM card.

🛠 Prerequisites

SIM card must not be in a Terminated state.

SIM card must not belong to a data pool.

⚠️ Notes

Basic plan subscription is processed synchronously.

Changing billing type is not allowed during subscription. For example, subscribing a postpaid plan for a prepaid SIM will result in failure.

For postpaid plans, cycles parameter is ignored; the plan is treated as having no fixed term.

📏 Business Rules

Upon successful subscription, the plan is not activated by default. Use the activation API to enable it.

Multiple basic plans can be subscribed for the same SIM. Each plan takes effect in sequence. The next plan becomes active only after the previous one’s cycle ends, even if the data is used up earlier.

🔄 Additional Parameter: `activate`

Only applicable for non-OTA SIMs.

Default value of activate is false — the plan will not be activated immediately.

When activate = true, the plan will be activated asynchronously after binding. You can query the async result.

Behavior under different SIM statuses when activate = true:

SIM Status Before Operation	`activate=true` Allowed	Behavior	Notes
Silent, Suspended, Retention	✅ Yes	Subscribe and activate plan	—
Active	✅ Yes	Current plan is paused (v3.0) or ended (v4.0); new plan is activated	Set `activate=false` if you want to keep the current plan running
Terminated (including expired contracts)	❌ No	Operation not allowed	—

📟 Return Codes

Code	Message	Suggested Action
CB-00-0000	Success	Plan added successfully
CB-01-0125	SIM is part of a data pool, operation not allowed	Contact Linksfield support
CB-01-0111	SIM has pending operations	Wait for the current operation to finish
CB-02-0003	Plan does not exist	Check and use a valid plan ID

➕ Add-On Plan `whitelist_only`

✅ Usage Scenario

Add data when the current basic plan's data is insufficient during the cycle.

🛠 Prerequisites

SIM status must be Active-live/23 (with an active sub-plan).

The active basic plan must support add-on packages.

SIM card must not be in a data pool.

⚠️ Notes

Add-on subscription is asynchronous. You can query the async result.

During async processing, the SIM is locked. Activation, suspension, resumption, or reset operations are disallowed on the same SIM.

📏 Business Rules

Add-on takes effect immediately upon successful subscription.

The add-on does not change the cycle duration of the basic plan. It expires when the cycle ends.

Multiple add-ons (same or different) can be subscribed in one cycle.

If the SIM is suspended via Suspend v2 (async), the add-on becomes immediately invalid.

If resumed via Resume (async), the add-on will not be restored.

🧪 SDK API Usage

SDK Version 1.0.9 or above is required

1. Without `activate` parameter:

2. With `activate` parameter:

3. With `clientToken`:

application/json

Body

Examples

SuccessException

{
    "data": {
        "order_id": "SO-123456578845"
    },
    "status": {
        "code": "CB-00-0000",
        "message": "Success",
        "detail": "https://apidoc-cn.iotcube.link/"
    }
}

📦 Basic Plan

✅ Usage Scenario

🛠 Prerequisites

⚠️ Notes

📏 Business Rules

🔄 Additional Parameter: `activate`

📟 Return Codes

➕ Add-On Plan `whitelist_only`

✅ Usage Scenario

🛠 Prerequisites

⚠️ Notes

📏 Business Rules

🧪 SDK API Usage

1. Without `activate` parameter:

2. With `activate` parameter:

3. With `clientToken`:

Request

Request Code Samples

Responses

Add Bundle

📦 Basic Plan#

✅ Usage Scenario#

🛠 Prerequisites#

⚠️ Notes#

📏 Business Rules#

🔄 Additional Parameter: activate#

📟 Return Codes#

➕ Add-On Plan whitelist_only#

✅ Usage Scenario#

🛠 Prerequisites#

⚠️ Notes#

📏 Business Rules#

🧪 SDK API Usage#

1. Without activate parameter:#

2. With activate parameter:#

3. With clientToken:#

Request

Request Code Samples

Responses

📦 Basic Plan

✅ Usage Scenario

🛠 Prerequisites

⚠️ Notes

📏 Business Rules

🔄 Additional Parameter: `activate`

📟 Return Codes

➕ Add-On Plan `whitelist_only`

✅ Usage Scenario

🛠 Prerequisites

⚠️ Notes

📏 Business Rules

🧪 SDK API Usage

1. Without `activate` parameter:

2. With `activate` parameter:

3. With `clientToken`: