Skip to main content
POST
/
subscriptions
Create subscription
curl --request POST \
  --url https://apiv2.example.com/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "productOfferingId": "<string>",
  "customerId": "<string>",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "metadata": {}
  },
  "referenceId": "crm-subscription-12345",
  "scheduleActivationAt": "2024-01-15",
  "extensions": {},
  "display": "<string>",
  "metadata": {}
}
'
{
  "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"
    }
  },
  "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"
      }
    }
  },
  "porting": {
    "msisdn": "<string>",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2023-12-25"
  },
  "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

Body

application/json

Create a new subscription for a customer.

Activation Options:

  1. Immediate activation: Provide activation data without scheduleActivationAt
  2. Scheduled activation: Provide activation data with scheduleActivationAt for future activation
  3. Shell subscription: Omit activation data to create a subscription that will be activated later

When to use shell subscriptions:

  • When activation details are not yet available (e.g., waiting for SIM card delivery)
  • When activation requires additional approval or processing
  • When bulk-creating subscriptions for later activation

Note: This endpoint is disabled when Seamless OS manages billing. In that case, subscriptions are created through orders.

​
productOfferingId
string
required

The unique identifier for the product offering to subscribe to.

This controls what type of subscription is being created.

​
customerId
string
required

The identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer.

​
subscriber
object
required

Subscriber details for this subscription.

​
referenceId
string

Optional reference ID to assign to the subscription. Must be unique per tenant. Once set, this value can be used in place of the subscriptionId in path parameters and request bodies across the API.

Maximum string length: 255
Example:

"crm-subscription-12345"

​
activation
object

Activation configuration for this subscription.

When to provide:

  • Provide activation details to create an active subscription immediately or scheduled for the future
  • Omit to create a "shell" subscription that must be activated later via the activate endpoint

Use cases:

  • Immediate activation: Provide activation data without scheduleActivationAt
  • Scheduled activation: Provide activation data with scheduleActivationAt set to a future date
  • Deferred activation: Omit activation data entirely - use the activate endpoint later when ready
​
scheduleActivationAt
string<date>

Date when the subscription should be activated in the network.

Only applicable when activation data is provided. If omitted, activation will be immediate or as soon as network resources are available.

Note: Network availability and porting timelines may affect the exact activation time. This date is a preference, not a guarantee.

Example:

"2024-01-15"

​
extensions
object

Additional subscription extensions fields for custom subscription types.

​
display
string

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

​
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

The created subscription.

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

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

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

​
subscriber
object

A subscriber is a user that has a subscription.

​
extensions
object

Additional subscription extensions fields provided for custom subscription types.

​
pendingMsisdn
object

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

​
pendingStatus
object

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

​
pendingProductOffering
object

Pending product offering change.

​
porting
object

Number porting information for subscriptions, indicating scheduled number transfers.

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

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