Cancel subscription

curl --request POST \
  --url https://apiv2.example.com/subscriptions/{subscriptionId}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "cancelAt": {
    "nextDay": true
  },
  "comment": "Switching to a different provider",
  "metadata": {}
}
'

import requests

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

payload = {
    "cancelAt": { "nextDay": True },
    "comment": "Switching to a different provider",
    "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({
    cancelAt: {nextDay: true},
    comment: 'Switching to a different provider',
    metadata: {}
  })
};

fetch('https://apiv2.example.com/subscriptions/{subscriptionId}/cancel', 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}/cancel",
  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([
    'cancelAt' => [
        'nextDay' => true
    ],
    'comment' => 'Switching to a different provider',
    '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}/cancel"

	payload := strings.NewReader("{\n  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\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}/cancel")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\n  \"metadata\": {}\n}"

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

{
  "subscriptionId": "<string>",
  "status": "PENDING",
  "type": "<string>",
  "display": "<string>",
  "msisdn": "<string>",
  "customer": {
    "customerId": "<string>",
    "name": "<string>"
  },
  "sim": {
    "esim": true,
    "imei": "<string>",
    "iccid": "<string>"
  },
  "activatedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "referenceId": "crm-subscription-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"
  },
  "subscriber": {
    "subscriberId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "address": {
      "street1": "500 S Main St",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "street2": "Apt 1",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "extensions": {},
  "pendingMsisdn": {
    "msisdn": "<string>",
    "scheduledAt": "2023-12-25"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2023-12-25"
  },
  "pendingProductOffering": {
    "scheduledAt": "2023-12-25",
    "product": {
      "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"
    }
  },
  "porting": {
    "msisdn": "<string>",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2023-12-25"
  },
  "cancelledAt": "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}

cancel

Cancel subscription

curl --request POST \
  --url https://apiv2.example.com/subscriptions/{subscriptionId}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "cancelAt": {
    "nextDay": true
  },
  "comment": "Switching to a different provider",
  "metadata": {}
}
'

import requests

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

payload = {
    "cancelAt": { "nextDay": True },
    "comment": "Switching to a different provider",
    "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({
    cancelAt: {nextDay: true},
    comment: 'Switching to a different provider',
    metadata: {}
  })
};

fetch('https://apiv2.example.com/subscriptions/{subscriptionId}/cancel', 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}/cancel",
  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([
    'cancelAt' => [
        'nextDay' => true
    ],
    'comment' => 'Switching to a different provider',
    '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}/cancel"

	payload := strings.NewReader("{\n  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\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}/cancel")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"cancelAt\": {\n    \"nextDay\": true\n  },\n  \"comment\": \"Switching to a different provider\",\n  \"metadata\": {}\n}"

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

{
  "subscriptionId": "<string>",
  "status": "PENDING",
  "type": "<string>",
  "display": "<string>",
  "msisdn": "<string>",
  "customer": {
    "customerId": "<string>",
    "name": "<string>"
  },
  "sim": {
    "esim": true,
    "imei": "<string>",
    "iccid": "<string>"
  },
  "activatedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "referenceId": "crm-subscription-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"
  },
  "subscriber": {
    "subscriberId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "address": {
      "street1": "500 S Main St",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "street2": "Apt 1",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "extensions": {},
  "pendingMsisdn": {
    "msisdn": "<string>",
    "scheduledAt": "2023-12-25"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2023-12-25"
  },
  "pendingProductOffering": {
    "scheduledAt": "2023-12-25",
    "product": {
      "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"
    }
  },
  "porting": {
    "msisdn": "<string>",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2023-12-25"
  },
  "cancelledAt": "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 cancel a subscription.

cancelAt

CancelNextDay · object

required

When the subscription should be cancelled.

CancelNextDay
CancelAtBeginningOfNextMonth
CancelAtDate

Show child attributes

churn

enum<string>

Standardized reason for the cancellation used for reporting and analysis.

If OTHER is provided, please also provide a comment.

Available options:

BETTER_DEAL_PRICE,

NOT_HAPPY_MISSING_FUNCTIONS,

NOT_HAPPY_COVERAGE_SLA,

NOT_HAPPY_COMPLEX_ADMIN,

NOT_HAPPY_SUPPORT_ENGAGEMENT,

FRAUD,

FRAUD_ATTEMPT,

TEST_OR_MARKETING,

NO_NEED,

WRONG_ORDER,

OTHER

comment

string

Optional comment about the cancellation.

Example:

"Switching to a different provider"

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

Subscription cancellation scheduled successfully.

A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.

subscriptionId

string

required

The unique identifier for the subscription.

status

enum<string>

required

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED,

SUSPENDED

type

string

required

The type of subscription, categorizing the service into various telecommunications service types.

display

string

required

The display name for the subscription, typically a pretty-print of the msisdn.

msisdn

string

required

The currently active phone number for this subscription.

customer

object

required

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes

sim

object

required

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes

activatedAt

string<date-time>

required

The date and time when the subscription was activated.

createdAt

string<date-time>

required

The date and time when the subscription was created.

updatedAt

string<date-time>

required

The date and time when the subscription was last updated.

referenceId

string

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

Maximum string length: 255

Example:

"crm-subscription-12345"

productOffering

object

Embedded representation of a product offering.

Show child attributes

subscriber

object

A subscriber is a user that has a subscription.

Show child attributes

extensions

object

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

pendingMsisdn

object

Details about when a pending phone number change is scheduled for this subscription.

Show child attributes

pendingStatus

object

Details about when a pending status change is scheduled for this subscription.

Show child attributes

pendingProductOffering

object

Pending product offering change.

Show child attributes

porting

object

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

Show child attributes

cancelledAt

string<date-time>

The date and time when the subscription 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.

Show child attributes

Getting started

Guides

Overview

API reference

Cancel subscription

Authorizations

Headers

Path Parameters

Body

Response