Subscriptions

Manage subscriptions and subscription.

List subscriptions

GET/subscriptions

List all subscriptions.

Will return all subscriptions the requester has access to.

Query parameters

customerIdarray of string

Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

statusarray of SubscriptionStatus

The status of the subscription to filter by.

typearray of SubscriptionType

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of subscriptions.

application/json

A list of subscriptions.

object

itemsarray of Subscriptionrequired

Show child attributes

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes

nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions

curl https://apiv2.example.com/api/v2/subscriptions \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "referenceId": "crm-subscription-12345",
      "status": "ACTIVATED",
      "type": "CELL",
      "display": "(555) 123-4567",
      "msisdn": "+15551234567",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "Acme Corp"
      },
      "productOffering": {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Seamless 10GB",
        "price": {
          "netPriceMinor": 2999,
          "currency": "USD",
          "priceType": "RECURRING",
          "billingCycle": {
            "period": "MONTHLY",
            "interval": 1
          },
          "standardDiscount": {
            "amountMinor": 500
          },
          "bindingContract": {
            "duration": {
              "unit": "MONTHS",
              "value": 12
            },
            "discount": {
              "amountMinor": 200
            }
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 300
            }
          },
          "currencyOptionsMinor": {
            "USD": 2999,
            "SEK": 29900
          }
        }
      },
      "subscriber": {
        "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "sim": {
        "esim": true,
        "iccid": "8901240197155182976"
      },
      "activatedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "costCenter": "eng-42"
      }
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Create subscription

POST/subscriptions

Create a new subscription for a customer.

Activation Modes:

Immediate Activation
- Provide complete activation data in the request
- Omit scheduleActivationAt or set to today's date
- Subscription activates immediately (network availability permitting)
Scheduled Activation
- Provide complete activation data in the request
- Set scheduleActivationAt to a future date
- Subscription activates on or after the specified date
Deferred Activation (Shell Subscription)
- Omit activation data from the request
- Subscription created in PENDING state
- Use the activate endpoint later when activation details are available

Common use cases:

Standard activation: Customer has all details ready (number choice, SIM type, porting info)
Scheduled activation: Activate on a specific date (e.g., start of billing cycle, go-live date)
Shell subscription: Bulk subscription creation, waiting for SIM delivery, phased onboarding

Note: This endpoint may be disabled when Seamless OS manages billing. In that configuration, subscriptions are created through the orders endpoint instead.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyCreateSubscriptionRequestrequiredapplication/json

Create a new subscription for a customer.

Activation Options:

Immediate activation: Provide activation data without scheduleActivationAt
Scheduled activation: Provide activation data with scheduleActivationAt for future activation
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.

productOfferingIdstringrequired

The unique identifier for the product offering to subscribe to.

This controls what type of subscription is being created.

customerIdstringrequired

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.

referenceIdstringmax length 255

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.

activationobject

Everything needed to bring the subscription online in the mobile network: the phone number (a specific number, a leased number, or empty for automatic assignment), the SIM configuration (eSIM or physical SIM), and optional porting details when the subscriber keeps their existing number from another carrier.

When to provide:

Provide activation details to have the subscription provisioned in the network — immediately, or on the date given in scheduleActivationAt
Omit to create a "shell" subscription that stays in PENDING status until you activate it later via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are not yet known

Show child attributes

msisdnstring

The phone number for this subscription.

Leave empty to have a number automatically assigned from the available pool
Provide a specific number when using a leased number from the number pool
Provide the number to be ported when transferring from another carrier

leaseTokenstring

Token received when leasing a number from the available number pool.

Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers.

portingobject

Details required to port (transfer) an existing phone number from another carrier.

Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements.

Show child attributes

detailsone ofrequired

Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.

Show child attributes

simobjectrequired

SIM card technology and configuration for this subscription.

Show child attributes

esimbooleanrequired

Whether this subscription uses eSIM (embedded SIM) technology.

true: Digital eSIM profile will be provisioned to the device
false: Physical SIM card will be used

iccidstring

Integrated Circuit Card Identifier (ICCID) of an existing SIM card.

Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM.

deliveryAddressobject

The address a physical SIM card is posted to.

An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

scheduleActivationAtstringdate

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.

extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes

*string

displaystring

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

subscriberobjectrequired

Subscriber details for this subscription.

Show child attributes

namestringrequired

The full name of the subscriber.

emailstringemail

The email address of the subscriber.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

201

The created subscription.

application/json

The created subscription.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions

curl https://apiv2.example.com/api/v2/subscriptions \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "referenceId": "crm-subscription-12345",
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000"
    },
    "deliveryAddress": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "scheduleActivationAt": "2024-01-15",
  "extensions": {
    "propertyName": "string"
  },
  "display": "John'\''s work phone",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "metadata": {
      "propertyName": "string"
    }
  },
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productOfferingId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
    customerId: 'a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d',
    referenceId: 'crm-subscription-12345',
    activation: {
      msisdn: '+15551234567',
      leaseToken: 'lease_abc123def456',
      porting: {
        details: {
          accountNumber: '987654321',
          passcode: '123456',
          firstName: 'John',
          lastName: 'Doe',
          address: {
            street: '500 S Main St',
            street1: 'string',
            street2: 'Apt 1',
            city: 'Natick',
            zip: '01701',
            country: 'US',
            state: 'CA',
            region: 'Ontario',
            attention: 'John Doe'
          }
        }
      },
      sim: {
        esim: true,
        iccid: '8931440400000000000'
      },
      deliveryAddress: {
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        city: 'Natick',
        zip: '01701',
        country: 'US',
        state: 'CA',
        region: 'Ontario',
        attention: 'John Doe'
      }
    },
    scheduleActivationAt: '2024-01-15',
    extensions: {
      propertyName: 'string'
    },
    display: 'John's work phone',
    subscriber: {
      name: 'John Doe',
      email: 'john.doe@example.com',
      address: {
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        city: 'Natick',
        zip: '01701',
        country: 'US',
        state: 'CA',
        region: 'Ontario',
        attention: 'John Doe'
      },
      metadata: {
        propertyName: 'string'
      }
    },
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "referenceId": "crm-subscription-12345",
      "activation": {
        "msisdn": "+15551234567",
        "leaseToken": "lease_abc123def456",
        "porting": {
          "details": {
            "accountNumber": "987654321",
            "passcode": "123456",
            "firstName": "John",
            "lastName": "Doe",
            "address": {
              "street": "500 S Main St",
              "street1": "string",
              "street2": "Apt 1",
              "city": "Natick",
              "zip": "01701",
              "country": "US",
              "state": "CA",
              "region": "Ontario",
              "attention": "John Doe"
            }
          }
        },
        "sim": {
          "esim": True,
          "iccid": "8931440400000000000"
        },
        "deliveryAddress": {
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      },
      "scheduleActivationAt": "2024-01-15",
      "extensions": {
        "propertyName": "string"
      },
      "display": "John's work phone",
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "address": {
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        },
        "metadata": {
          "propertyName": "string"
        }
      },
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions"

	payload := strings.NewReader(`{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "referenceId": "crm-subscription-12345",
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000"
    },
    "deliveryAddress": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "scheduleActivationAt": "2024-01-15",
  "extensions": {
    "propertyName": "string"
  },
  "display": "John's work phone",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "metadata": {
      "propertyName": "string"
    }
  },
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get subscription

GET/subscriptions/{subscriptionId}

Retrieve detailed information about a specific subscription using its unique identifier.

Path parameters

subscriptionIdstringrequired

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.

Responses

200

A subscription object.

application/json

A subscription object.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "ACTIVATED",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Corp"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Seamless 10GB",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "RECURRING",
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "standardDiscount": {
        "amountMinor": 500
      },
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 12
        },
        "discount": {
          "amountMinor": 200
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 300
        }
      },
      "currencyOptionsMinor": {
        "USD": 2999,
        "SEK": 29900
      }
    }
  },
  "subscriber": {
    "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "costCenter": "eng-42"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Activate subscription

POST/subscriptions/{subscriptionId}/activate

Activate a pending subscription by providing the necessary network activation details.

Use this endpoint when a subscription was created as a "shell" without activation data.

If the subscription is not pending, an error will be returned.

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyActivateSubscriptionRequestrequiredapplication/json

Request to activate a pending subscription in the telecommunications network.

Use this endpoint to activate subscriptions that were created as "shells" without initial activation data, or to activate subscriptions that are in a state where network activation is needed.

Activation timing:

Omit scheduleActivationAt for immediate activation (or as soon as network resources are available)
Provide scheduleActivationAt to schedule activation for a future date

activationobjectrequired

Complete activation configuration required to bring the subscription online in the network.

This includes the phone number assignment, SIM card details, and any number porting information.

Configuration and details required to activate a subscription in the telecommunications network.

This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services.

Show child attributes

msisdnstring

The phone number for this subscription.

Leave empty to have a number automatically assigned from the available pool
Provide a specific number when using a leased number from the number pool
Provide the number to be ported when transferring from another carrier

leaseTokenstring

Token received when leasing a number from the available number pool.

Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers.

portingobject

Details required to port (transfer) an existing phone number from another carrier.

Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements.

Show child attributes

detailsone ofrequired

Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.

Show child attributes

simobjectrequired

SIM card technology and configuration for this subscription.

Show child attributes

esimbooleanrequired

Whether this subscription uses eSIM (embedded SIM) technology.

true: Digital eSIM profile will be provisioned to the device
false: Physical SIM card will be used

iccidstring

Integrated Circuit Card Identifier (ICCID) of an existing SIM card.

Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM.

deliveryAddressobject

The address a physical SIM card is posted to.

An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

scheduleActivationAtstringdate

Date when the subscription should be scheduled for activation.

If not provided, activation will be immediate or as soon as possible based on network availability.

Note: Network availability and porting timelines may affect exact timing. This date is considered a preference, not a guarantee. The actual activation may occur on or after this date.

Responses

200

Subscription activation scheduled or completed successfully.

application/json

Subscription activation scheduled or completed successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/activate

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "sim": {
      "esim": true
    }
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    activation: {
      msisdn: '+15551234567',
      leaseToken: 'lease_abc123def456',
      sim: {
        esim: true
      }
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "activation": {
        "msisdn": "+15551234567",
        "leaseToken": "lease_abc123def456",
        "sim": {
          "esim": True
        }
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate"

	payload := strings.NewReader(`{
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "sim": {
      "esim": true
    }
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "ACTIVATED",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Corp"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Seamless 10GB",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "RECURRING",
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "standardDiscount": {
        "amountMinor": 500
      },
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 12
        },
        "discount": {
          "amountMinor": 200
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 300
        }
      },
      "currencyOptionsMinor": {
        "USD": 2999,
        "SEK": 29900
      }
    }
  },
  "subscriber": {
    "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get subscription in-porting

GET/subscriptions/{subscriptionId}/in-porting

Retrieve the current porting information for a subscription that is in the process of porting in a number.

Path parameters

subscriptionIdstringrequired

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.

Responses

200

Porting information retrieved successfully.

application/json

Porting information retrieved successfully.

objectPorting

A request to transfer (port) a phone number between carriers, either into this platform from the subscriber's previous carrier or out to another carrier. Tracks the number, the transfer's progress, and the ownership details required by the carriers involved.

msisdnstringrequired

The phone number to be ported, in E.164 format.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdate

The date when the porting is scheduled to occur.

detailsone ofrequired

Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.

Show child attributes

PortingDetailsUSPortingDetailsSweden

accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

updatedAtstringdate-time

The timestamp of the last update to the porting request.

createdAtstringdate-timerequired

The timestamp when the porting request was created.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/in-porting

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "msisdn": "+15551234567",
  "status": "PENDING",
  "direction": "INBOUND",
  "scheduledAt": "2024-02-01",
  "details": {
    "accountNumber": "987654321",
    "passcode": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "updatedAt": "2024-01-20T09:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Update subscription porting details

POST/subscriptions/{subscriptionId}/in-porting

Update the porting details for a subscription that is in the process of porting in a number. This endpoint allows you to modify porting information while the port is still pending or in progress.

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyUpdatePortingRequestrequiredapplication/json

Request to correct or complete the porting details of a subscription's in-progress port-in, for example after the losing carrier rejected the transfer because the owner details did not match.

detailsone ofrequired

Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.

Show child attributes

PortingDetailsUSPortingDetailsSweden

accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

Responses

200

Porting details updated successfully.

application/json

Porting details updated successfully.

object

subscriptionobject

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

Show child attributes

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

portingInfoobject

Updated porting information and status.

Show child attributes

portingIdstring

The unique identifier for this porting request.

statusenum<string>

Current status of the porting process.

values

pending
in_progress
scheduled
completed
failed

estimatedCompletionstringdate-time

Estimated completion time for the port.

nextStepsarray of string

Next steps required to complete the porting process.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/in-porting

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "details": {
    "identity": "199001011234"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    details: {
      identity: '199001011234'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "details": {
        "identity": "199001011234"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting"

	payload := strings.NewReader(`{
  "details": {
    "identity": "199001011234"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscription": {
    "subscriptionId": "7a1b9c3d-2e4f-4a6b-8c0d-9e8f7a6b5c4d",
    "status": "ACTIVATED",
    "type": "CELL",
    "display": "073-111 00 00",
    "msisdn": "+46731110000",
    "customer": {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Volt AB"
    },
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobil 10GB",
      "price": {
        "netPriceMinor": 24900,
        "currency": "SEK",
        "priceType": "RECURRING",
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "standardDiscount": {
          "amountMinor": 5000
        },
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 12
          },
          "discount": {
            "amountMinor": 2000
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 3000
          }
        },
        "currencyOptionsMinor": {
          "SEK": 24900,
          "USD": 2499
        }
      }
    },
    "subscriber": {
      "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
      "name": "Anna Andersson",
      "email": "anna.andersson@example.com"
    },
    "sim": {
      "esim": false,
      "iccid": "8946071234567890123"
    },
    "pendingMsisdn": {
      "msisdn": "+46701234567",
      "scheduledAt": "2025-02-01"
    },
    "porting": {
      "msisdn": "+46701234567",
      "status": "IN_PROGRESS",
      "direction": "INBOUND",
      "scheduledAt": "2025-02-01"
    },
    "activatedAt": "2025-01-10T09:00:00Z",
    "createdAt": "2025-01-08T08:00:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "portingInfo": {
    "portingId": "e5f6a7b8-c9d0-4123-8456-789abcdef012",
    "status": "in_progress",
    "estimatedCompletion": "2025-02-01T00:00:00Z",
    "nextSteps": [
      "Waiting for the current provider to respond to the porting request",
      "No action required at this time"
    ]
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Change subscription product offering

PUT/subscriptions/{subscriptionId}/product-offering-change

Change the product offering of a subscription (upgrade or downgrade).

To get a list of to what and when the subscription can be changed, get change options for the subscription.

When the change takes effect is dictated by what product offering is chosen, which in its place depends on the network setup, billing cycle.

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyChangeSubscriptionProductOfferingRequestrequiredapplication/json

Request to change the product offering of a subscription.

productOfferingIdstringrequired

The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to.

scheduledAtstringdate

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

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Product offering change scheduled.

application/json

Product offering change scheduled.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

PUT /subscriptions/{subscriptionId}/product-offering-change

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productOfferingId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
    scheduledAt: '2024-02-01',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.put(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "scheduledAt": "2024-02-01",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change"

	payload := strings.NewReader(`{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get change options for subscription

GET/subscriptions/{subscriptionId}/product-offering-options

Get all available product offerings a subscription can be changed to and when the change can take effect.

When the subscription can be changed typically depends on the network setup, billing cycle, and current product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date.

Path parameters

subscriptionIdstringrequired

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.

Responses

200

Available change options.

application/json

Available change options.

object

itemsarray of ProductOfferingOptionrequired

Show child attributes

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

changeScheduleenum<string>required

The schedule type for when a product offering change can take effect.

INSTANT: Change takes effect immediately
FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month
NEXT_RENEWAL_DAY: Change takes effect on the next renewal date
NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day

values

INSTANT
FIRST_OF_NEXT_MONTH
NEXT_RENEWAL_DAY
NEXT_PAYMENT_DAY

changeScheduleDatestringdaterequired

The date when the product offering change can take effect.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/product-offering-options

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "productOffering": {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Mobile Unlimited",
        "price": {
          "netPriceMinor": 2999,
          "currency": "USD",
          "priceType": "ONE_TIME",
          "bindingContract": {
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "source": "STANDARD",
              "invoicingDescription": "Campaign discount"
            }
          },
          "billingCycle": {
            "period": "MONTHLY",
            "interval": 1
          },
          "currencyOptionsMinor": {
            "propertyName": 1
          }
        },
        "group": {
          "productOfferingGroupId": "mobile-plans",
          "name": "Mobile Plans",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "internalDescription": "Core mobile offerings targeting consumer and business segments"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
      },
      "changeSchedule": "INSTANT",
      "changeScheduleDate": "2024-02-01"
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Cancel subscription

POST/subscriptions/{subscriptionId}/cancel

This endpoint allows cancelling a subscription with various timing options:

Next day cancellation
Beginning of next month cancellation
Specific date cancellation

Standardized churn reasons help with reporting and analysis.

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyCancelSubscriptionRequestrequiredapplication/json

Request to cancel a subscription.

cancelAtone ofrequired

When the subscription should be cancelled.

Show child attributes

CancelNextDayCancelAtBeginningOfNextMonthCancelAtDate

nextDaybooleanrequired

Cancel the subscription the next day.

nextMonthbooleanrequired

Cancel the subscription at the beginning of next month.

datestringdaterequired

Cancel the subscription on a specific date.

churnenum<string>

Standardized reason for the cancellation used for reporting and analysis.

If OTHER is provided, please also provide a comment.

values

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

commentstring

Optional comment about the cancellation.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Subscription cancellation scheduled successfully.

application/json

Subscription cancellation scheduled successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/cancel

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "cancelAt": {
    "nextDay": true
  },
  "churn": "BETTER_DEAL_PRICE",
  "comment": "Switching to a different provider",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cancelAt: {
      nextDay: true
    },
    churn: 'BETTER_DEAL_PRICE',
    comment: 'Switching to a different provider',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "cancelAt": {
        "nextDay": True
      },
      "churn": "BETTER_DEAL_PRICE",
      "comment": "Switching to a different provider",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel"

	payload := strings.NewReader(`{
  "cancelAt": {
    "nextDay": true
  },
  "churn": "BETTER_DEAL_PRICE",
  "comment": "Switching to a different provider",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Suspend subscription

POST/subscriptions/{subscriptionId}/suspend

Temporarily suspend a subscription. The customer continues to pay but service is disabled. This is typically used for payment issues or fraud prevention.

Supports flexible scheduling:

Immediate suspension
Next day suspension
Beginning of next month suspension
Specific date suspension

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodySuspendSubscriptionRequestrequiredapplication/json

Request to temporarily suspend a subscription. The customer continues to pay but service is disabled.

scheduledAtstringdate

Suspend the subscription on a specific date.

reasonstring

Optional reason for the suspension.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Subscription suspension scheduled successfully.

application/json

Subscription suspension scheduled successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/suspend

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scheduledAt": "2024-02-01",
  "reason": "Payment overdue",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    scheduledAt: '2024-02-01',
    reason: 'Payment overdue',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "scheduledAt": "2024-02-01",
      "reason": "Payment overdue",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend"

	payload := strings.NewReader(`{
  "scheduledAt": "2024-02-01",
  "reason": "Payment overdue",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Pause subscription

POST/subscriptions/{subscriptionId}/pause

Pause a subscription. The customer stops paying and service is disabled. This is typically used when a customer wants to temporarily stop service.

Supports flexible scheduling:

Immediate pause
Next day pause
Beginning of next month pause
Specific date pause

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyPauseSubscriptionRequestrequiredapplication/json

Request to pause a subscription. The customer stops paying and service is disabled.

scheduledAtstringdate

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

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Subscription pause scheduled successfully.

application/json

Subscription pause scheduled successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/pause

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    scheduledAt: '2024-02-01',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "scheduledAt": "2024-02-01",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause"

	payload := strings.NewReader(`{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Restore subscription

POST/subscriptions/{subscriptionId}/restore

Restore a suspended, paused, or blocked subscription back to active state.

Supports flexible scheduling:

Immediate restore
Next day restoration
Beginning of next month restoration
Specific date restoration

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyRestoreSubscriptionRequestrequiredapplication/json

Request to restore a suspended, paused, or blocked subscription back to active state.

scheduledAtstringdate

Restore the subscription on a specific date.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

Subscription restoration scheduled successfully.

application/json

Subscription restoration scheduled successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/restore

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    scheduledAt: '2024-02-01',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "scheduledAt": "2024-02-01",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore"

	payload := strings.NewReader(`{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Block SIM

POST/subscriptions/{subscriptionId}/block-sim

Block the SIM card on a subscription, so it can no longer use the network. Use this when a subscriber reports their SIM lost or stolen.

The block takes effect immediately and cannot be scheduled. Any changes already scheduled on the subscription are cancelled, except an in-progress number port or a scheduled SIM card change, which both continue — a cancelled port would lose the subscriber their number.

Blocking is not reversible through this endpoint: issue a new SIM card to bring the subscription back into service.

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

Responses

200

SIM blocked successfully.

application/json

SIM blocked successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/block-sim

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Change subscription SIM card

POST/subscriptions/{subscriptionId}/change-sim

Change the SIM card (ICC/ICCID) for a subscription. This is used when replacing a lost, damaged, or upgraded SIM card.

Supports flexible scheduling:

Immediate SIM card change
Next day SIM card change
Beginning of next month SIM card change
Specific date SIM card change

Path parameters

subscriptionIdstringrequired

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.

Headers

X-Idempotency-Keystringmax length 256

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.

BodyChangeSubscriptionSimRequestrequiredapplication/json

Request to change the SIM card (ICC/ICCID) for a subscription.

scheduledAtstringdate

Change the SIM card on a specific date.

iccstringrequired

The ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile.

simCardTypeenum<string>required

The type of SIM card being installed.

values

PHYSICAL
ESIM

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

Responses

200

SIM card change scheduled successfully.

application/json

SIM card change scheduled successfully.

objectSubscription

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

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

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.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

streetstring

The first line of the address, typically street and house number.

street1stringdeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

simobjectrequired

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

esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /subscriptions/{subscriptionId}/change-sim

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scheduledAt": "2024-02-01",
  "icc": "89012345678901234567",
  "simCardType": "PHYSICAL",
  "metadata": {
    "propertyName": "string"
  }
}'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    scheduledAt: '2024-02-01',
    icc: '89012345678901234567',
    simCardType: 'PHYSICAL',
    metadata: {
      propertyName: 'string'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "scheduledAt": "2024-02-01",
      "icc": "89012345678901234567",
      "simCardType": "PHYSICAL",
      "metadata": {
        "propertyName": "string"
      }
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim"

	payload := strings.NewReader(`{
  "scheduledAt": "2024-02-01",
  "icc": "89012345678901234567",
  "simCardType": "PHYSICAL",
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_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(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "source": "STANDARD",
        "invoicingDescription": "Campaign discount"
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "source": "STANDARD",
          "invoicingDescription": "Campaign discount"
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "source": "STANDARD",
            "invoicingDescription": "Campaign discount"
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get eSIM QR code

GET/subscriptions/{subscriptionId}/esim/qrcode

Retrieve QR code data and hosted URL for eSIM profile download.

Returns both the raw QR code data (LPA format) and a hosted URL for the QR code image. Only available for eSIM subscriptions (sim.esim: true). QR codes expire for security and should be treated as sensitive data.

Path parameters

subscriptionIdstringrequired

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.

Responses

200

eSIM QR code data and hosted URL retrieved successfully.

application/json

eSIM QR code data and hosted URL retrieved successfully.

objectEsimQrCode

eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL.

subscriptionIdstringrequired

The unique identifier of the subscription this QR code belongs to.

qrCodeDatastringrequired

The QR code data string that contains the eSIM profile download information (LPA format).

qrCodeUrlstringuri

Hosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead.

expiresAtstringdate-time

When the QR code and any hosted URL expire. After this time, a new QR code should be requested. Omitted when no expiry applies.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/esim/qrcode

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "qrCodeData": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012",
  "qrCodeUrl": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "expiresAt": "2024-12-31T23:59:59Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Query parameters

Responses

Headers

Body·CreateSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Responses

Path parameters

Headers

Body·ActivateSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Responses

Path parameters

Headers

Body·UpdatePortingRequestrequiredapplication/json

Responses

Path parameters

Headers

Body·ChangeSubscriptionProductOfferingRequestrequiredapplication/json

Responses

Path parameters

Responses

Path parameters

Headers

Body·CancelSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Headers

Body·SuspendSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Headers

Body·PauseSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Headers

Body·RestoreSubscriptionRequestrequiredapplication/json

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Body·ChangeSubscriptionSimRequestrequiredapplication/json

Responses

Path parameters

Responses

BodyCreateSubscriptionRequestrequiredapplication/json

BodyActivateSubscriptionRequestrequiredapplication/json

BodyUpdatePortingRequestrequiredapplication/json

BodyChangeSubscriptionProductOfferingRequestrequiredapplication/json

BodyCancelSubscriptionRequestrequiredapplication/json

BodySuspendSubscriptionRequestrequiredapplication/json

BodyPauseSubscriptionRequestrequiredapplication/json

BodyRestoreSubscriptionRequestrequiredapplication/json

BodyChangeSubscriptionSimRequestrequiredapplication/json