---
title: Subscriptions
description: Manage subscriptions and subscription.
---

# Subscriptions

Manage subscriptions and subscription.

## [GET /subscriptions](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions)

List subscriptions

List all subscriptions.

Will return all subscriptions the requester has access to.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Query parameters

- `customerId` (`array of string`, optional) — 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.
- `status` (`array of SubscriptionStatus`, optional) — The status of the subscription to filter by.
- `type` (`array of SubscriptionType`, optional)
- `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return.
- `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor.

### Responses

#### 200

A list of subscriptions.

Type: `object`

- `items` (`array of Subscription`, required)
  - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription.
  - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — 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.
  - `status` (`enum<string>`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — 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
  - `type` (`string`, required, example CELL) — 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.
  - `display` (`string`, required, example (555) 123-4567) — 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.
  - `msisdn` (`string`, required, phone, example +15551234567) — 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.
  - `customer` (`object`, required) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
    - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details.
    - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers.
  - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details.
    - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
    - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views.
    - `price` (`object`, required) — 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.
      - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units.
      - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD").
      - `priceType` (`enum<string>`, required, one of ONE_TIME, RECURRING) — 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).
      - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
        - `duration` (`object`, required) — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `standardDiscount` (`object`, optional) — 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.
        - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
        - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
        - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `customUpfrontPayment` (`object`, optional) — 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.
        - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `billingCycle` (`object`, optional) — How often a recurring price is charged.
        - `period` (`enum<string>`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported.
        - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
      - `currencyOptionsMinor` (`object with string keys`, optional) — 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.
        - `*` (`integer`, optional, int64)
    - `group` (`object`, optional) — A product group organizes related product offerings.
      - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group.
      - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale.
      - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale.
      - `category` (`enum<string>`, required, one of 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, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — 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
      - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only.
    - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering.
  - `subscriber` (`object`, optional) — The person who uses the service on a subscription, as distinct from the customer who pays for it.
    - `subscriberId` (`string`, required, example d0e1f2a3-b4c5-6789-0123-456789012345) — The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
    - `name` (`string`, required, example John Doe) — The subscriber's full name.
    - `email` (`string`, optional, email, example john.doe@example.com) — The subscriber's email address, if one has been provided.
    - `address` (`object`, optional) — 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.
      - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
      - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
      - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
      - `city` (`string`, required, example Natick) — The city or municipality of the address.
      - `zip` (`string`, required, example 01701) — 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').
      - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
      - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
      - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
      - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
    - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created.
    - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated.
  - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields provided for custom subscription types.
    - `*` (`string`, optional)
  - `sim` (`object`, required) — SIM card information for the subscription. Sensitive details like PUK require separate API calls. Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.
    - `esim` (`boolean`, required, example true) — Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
    - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware. Only applicable for eSIM.
    - `iccid` (`string`, optional, example 8901240197155182976) — Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
  - `pendingMsisdn` (`object`, optional) — 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.
    - `msisdn` (`string`, required, phone, example +15559876543) — The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
    - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending number change is scheduled to occur.
  - `pendingStatus` (`object`, optional) — 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.
    - `status` (`enum<string>`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — 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
    - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur.
  - `pendingProductOffering` (`object`, optional) — 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.
    - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur.
    - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details.
      - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
      - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views.
      - `price` (`object`, required) — 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.
        - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units.
        - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD").
        - `priceType` (`enum<string>`, required, one of ONE_TIME, RECURRING) — 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).
        - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
          - `duration` (`object`, required) — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `discount` (`object`, optional) — 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.
            - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
            - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
              - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
              - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
            - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
            - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `standardDiscount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `customUpfrontPayment` (`object`, optional) — 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.
          - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
          - `discount` (`object`, optional) — 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.
            - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
            - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
              - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
              - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
            - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
            - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `billingCycle` (`object`, optional) — How often a recurring price is charged.
          - `period` (`enum<string>`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported.
          - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
        - `currencyOptionsMinor` (`object with string keys`, optional) — 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.
          - `*` (`integer`, optional, int64)
      - `group` (`object`, optional) — A product group organizes related product offerings.
        - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group.
        - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale.
        - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale.
        - `category` (`enum<string>`, required, one of 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, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — 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
        - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only.
      - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering.
  - `porting` (`object`, optional) — Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint.
    - `msisdn` (`string`, required, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number.
    - `status` (`enum<string>`, required, one of PENDING, IN_PROGRESS, SCHEDULED, COMPLETED, FAILED) — 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
    - `direction` (`enum<string>`, required, one of INBOUND, OUTBOUND) — 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.
    - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur.
  - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated.
  - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable).
  - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created.
  - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated.
  - `metadata` (`object with string keys`, optional) — 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.
    - `*` (`string`, optional)
- `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page.
  - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 429

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

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

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

## [POST /subscriptions](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions)

Create subscription

Create a new subscription for a customer.

**Activation Modes:**

1. **Immediate Activation**
   - Provide complete activation data in the request
   - Omit scheduleActivationAt or set to today's date
   - Subscription activates immediately (network availability permitting)

2. **Scheduled Activation**
   - Provide complete activation data in the request
   - Set scheduleActivationAt to a future date
   - Subscription activates on or after the specified date

3. **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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering to subscribe to. This controls what type of subscription is being created.
- `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — 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.
- `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — 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.
- `activation` (`object`, optional) — 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
  - `msisdn` (`string`, optional, example +15551234567) — 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
  - `leaseToken` (`string`, optional, example lease_abc123def456) — 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.
  - `porting` (`object`, optional) — 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.
    - `details` (`one of`, required) — 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.
      - One of: `PortingDetailsUS`
        - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand.
        - `passcode` (`string`, optional, example 123456) — 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.
        - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider.
        - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider.
        - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
          - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
          - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
          - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
          - `city` (`string`, required, example Natick) — The city or municipality of the address.
          - `zip` (`string`, required, example 01701) — 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').
          - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
          - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
          - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
          - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
      - One of: `PortingDetailsSweden`
        - `identity` (`string`, required, example 199001011234) — 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.
  - `sim` (`object`, required) — SIM card technology and configuration for this subscription.
    - `esim` (`boolean`, required, example true) — 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
    - `iccid` (`string`, optional, example 8931440400000000000) — 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.
  - `deliveryAddress` (`object`, optional) — 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.
    - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
    - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
    - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
    - `city` (`string`, required, example Natick) — The city or municipality of the address.
    - `zip` (`string`, required, example 01701) — 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').
    - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
    - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
    - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
    - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
- `scheduleActivationAt` (`string`, optional, date, example 2024-01-15) — 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.
- `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types.
  - `*` (`string`, optional)
- `display` (`string`, optional, example John's work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn.
- `subscriber` (`object`, required) — Subscriber details for this subscription.
  - `name` (`string`, required, example John Doe) — The full name of the subscriber.
  - `email` (`string`, optional, email, example john.doe@example.com) — The email address of the subscriber.
  - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
    - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
    - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
    - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
    - `city` (`string`, required, example Natick) — The city or municipality of the address.
    - `zip` (`string`, required, example 01701) — 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').
    - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
    - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
    - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
    - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
  - `metadata` (`object with string keys`, optional) — 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.
    - `*` (`string`, optional)
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 201

The created subscription.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 429

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

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [GET /subscriptions/{subscriptionId}](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId})

Get subscription

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Responses

#### 200

A subscription object.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

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

## [POST /subscriptions/{subscriptionId}/activate](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/activate)

Activate subscription

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `activation` (`object`, required) — 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.
  - `msisdn` (`string`, optional, example +15551234567) — 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
  - `leaseToken` (`string`, optional, example lease_abc123def456) — 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.
  - `porting` (`object`, optional) — 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.
    - `details` (`one of`, required) — 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.
      - One of: `PortingDetailsUS`
        - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand.
        - `passcode` (`string`, optional, example 123456) — 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.
        - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider.
        - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider.
        - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
          - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
          - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
          - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
          - `city` (`string`, required, example Natick) — The city or municipality of the address.
          - `zip` (`string`, required, example 01701) — 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').
          - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
          - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
          - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
          - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
      - One of: `PortingDetailsSweden`
        - `identity` (`string`, required, example 199001011234) — 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.
  - `sim` (`object`, required) — SIM card technology and configuration for this subscription.
    - `esim` (`boolean`, required, example true) — 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
    - `iccid` (`string`, optional, example 8931440400000000000) — 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.
  - `deliveryAddress` (`object`, optional) — 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.
    - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
    - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
    - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
    - `city` (`string`, required, example Natick) — The city or municipality of the address.
    - `zip` (`string`, required, example 01701) — 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').
    - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
    - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
    - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
    - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
- `scheduleActivationAt` (`string`, optional, date, example 2025-01-01) — 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.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 429

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

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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
    }
  }
}'
```

## [GET /subscriptions/{subscriptionId}/in-porting](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/in-porting)

Get subscription in-porting

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Responses

#### 200

Porting information retrieved successfully.

Type: [Porting](/api-reference/models.md#models/Porting)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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'
```

## [POST /subscriptions/{subscriptionId}/in-porting](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/in-porting)

Update subscription porting details

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `details` (`one of`, required) — 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.
  - One of: `PortingDetailsUS`
    - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand.
    - `passcode` (`string`, optional, example 123456) — 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.
    - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider.
    - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider.
    - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
      - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
      - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
      - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
      - `city` (`string`, required, example Natick) — The city or municipality of the address.
      - `zip` (`string`, required, example 01701) — 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').
      - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
      - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
      - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
      - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
  - One of: `PortingDetailsSweden`
    - `identity` (`string`, required, example 199001011234) — 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.

Type: `object`

- `subscription` (`object`, optional) — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
  - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription.
  - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — 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.
  - `status` (`enum<string>`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — 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
  - `type` (`string`, required, example CELL) — 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.
  - `display` (`string`, required, example (555) 123-4567) — 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.
  - `msisdn` (`string`, required, phone, example +15551234567) — 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.
  - `customer` (`object`, required) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
    - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details.
    - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers.
  - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details.
    - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
    - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views.
    - `price` (`object`, required) — 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.
      - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units.
      - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD").
      - `priceType` (`enum<string>`, required, one of ONE_TIME, RECURRING) — 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).
      - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
        - `duration` (`object`, required) — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `standardDiscount` (`object`, optional) — 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.
        - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
        - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
        - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `customUpfrontPayment` (`object`, optional) — 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.
        - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `billingCycle` (`object`, optional) — How often a recurring price is charged.
        - `period` (`enum<string>`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported.
        - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
      - `currencyOptionsMinor` (`object with string keys`, optional) — 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.
        - `*` (`integer`, optional, int64)
    - `group` (`object`, optional) — A product group organizes related product offerings.
      - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group.
      - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale.
      - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale.
      - `category` (`enum<string>`, required, one of 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, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — 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
      - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only.
    - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering.
  - `subscriber` (`object`, optional) — The person who uses the service on a subscription, as distinct from the customer who pays for it.
    - `subscriberId` (`string`, required, example d0e1f2a3-b4c5-6789-0123-456789012345) — The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
    - `name` (`string`, required, example John Doe) — The subscriber's full name.
    - `email` (`string`, optional, email, example john.doe@example.com) — The subscriber's email address, if one has been provided.
    - `address` (`object`, optional) — 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.
      - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
      - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
      - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
      - `city` (`string`, required, example Natick) — The city or municipality of the address.
      - `zip` (`string`, required, example 01701) — 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').
      - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
      - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
      - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
      - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
    - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created.
    - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated.
  - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields provided for custom subscription types.
    - `*` (`string`, optional)
  - `sim` (`object`, required) — SIM card information for the subscription. Sensitive details like PUK require separate API calls. Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.
    - `esim` (`boolean`, required, example true) — Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
    - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware. Only applicable for eSIM.
    - `iccid` (`string`, optional, example 8901240197155182976) — Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
  - `pendingMsisdn` (`object`, optional) — 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.
    - `msisdn` (`string`, required, phone, example +15559876543) — The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
    - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending number change is scheduled to occur.
  - `pendingStatus` (`object`, optional) — 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.
    - `status` (`enum<string>`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — 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
    - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur.
  - `pendingProductOffering` (`object`, optional) — 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.
    - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur.
    - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details.
      - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
      - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views.
      - `price` (`object`, required) — 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.
        - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units.
        - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD").
        - `priceType` (`enum<string>`, required, one of ONE_TIME, RECURRING) — 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).
        - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
          - `duration` (`object`, required) — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `discount` (`object`, optional) — 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.
            - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
            - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
              - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
              - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
            - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
            - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `standardDiscount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `customUpfrontPayment` (`object`, optional) — 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.
          - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
          - `discount` (`object`, optional) — 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.
            - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
            - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
              - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
              - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
            - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
            - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
        - `billingCycle` (`object`, optional) — How often a recurring price is charged.
          - `period` (`enum<string>`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported.
          - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
        - `currencyOptionsMinor` (`object with string keys`, optional) — 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.
          - `*` (`integer`, optional, int64)
      - `group` (`object`, optional) — A product group organizes related product offerings.
        - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group.
        - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale.
        - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale.
        - `category` (`enum<string>`, required, one of 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, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — 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
        - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only.
      - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering.
  - `porting` (`object`, optional) — Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint.
    - `msisdn` (`string`, required, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number.
    - `status` (`enum<string>`, required, one of PENDING, IN_PROGRESS, SCHEDULED, COMPLETED, FAILED) — 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
    - `direction` (`enum<string>`, required, one of INBOUND, OUTBOUND) — 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.
    - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur.
  - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated.
  - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable).
  - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created.
  - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated.
  - `metadata` (`object with string keys`, optional) — 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.
    - `*` (`string`, optional)
- `portingInfo` (`object`, optional) — Updated porting information and status.
  - `portingId` (`string`, optional) — The unique identifier for this porting request.
  - `status` (`enum<string>`, optional, one of pending, in_progress, scheduled, completed, failed) — Current status of the porting process.
  - `estimatedCompletion` (`string`, optional, date-time) — Estimated completion time for the port.
  - `nextSteps` (`array of string`, optional) — Next steps required to complete the porting process.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [PUT /subscriptions/{subscriptionId}/product-offering-change](/api-reference/subscriptions#tag/subscriptions/PUT/subscriptions/{subscriptionId}/product-offering-change)

Change subscription product offering

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to.
- `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

Product offering change scheduled.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [GET /subscriptions/{subscriptionId}/product-offering-options](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/product-offering-options)

Get change options for subscription

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Responses

#### 200

Available change options.

Type: `object`

- `items` (`array of ProductOfferingOption`, required)
  - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details.
    - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
    - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views.
    - `price` (`object`, required) — 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.
      - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units.
      - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD").
      - `priceType` (`enum<string>`, required, one of ONE_TIME, RECURRING) — 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).
      - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
        - `duration` (`object`, required) — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `standardDiscount` (`object`, optional) — 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.
        - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
        - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
          - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
          - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
        - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
        - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `customUpfrontPayment` (`object`, optional) — 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.
        - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
        - `discount` (`object`, optional) — 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.
          - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units.
          - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit.
            - `unit` (`enum<string>`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported.
            - `value` (`integer`, required, example 3) — How many of the unit the duration lasts.
          - `source` (`enum<string>`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.
          - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
      - `billingCycle` (`object`, optional) — How often a recurring price is charged.
        - `period` (`enum<string>`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported.
        - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
      - `currencyOptionsMinor` (`object with string keys`, optional) — 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.
        - `*` (`integer`, optional, int64)
    - `group` (`object`, optional) — A product group organizes related product offerings.
      - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group.
      - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale.
      - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale.
      - `category` (`enum<string>`, required, one of 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, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — 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
      - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only.
    - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering.
  - `changeSchedule` (`enum<string>`, required, one of INSTANT, FIRST_OF_NEXT_MONTH, NEXT_RENEWAL_DAY, NEXT_PAYMENT_DAY) — 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
  - `changeScheduleDate` (`string`, required, date, example 2024-02-01) — The date when the product offering change can take effect.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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'
```

## [POST /subscriptions/{subscriptionId}/cancel](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/cancel)

Cancel subscription

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `cancelAt` (`one of`, required) — When the subscription should be cancelled.
  - One of: `CancelNextDay`
    - `nextDay` (`boolean`, required, example true) — Cancel the subscription the next day.
  - One of: `CancelAtBeginningOfNextMonth`
    - `nextMonth` (`boolean`, required, example true) — Cancel the subscription at the beginning of next month.
  - One of: `CancelAtDate`
    - `date` (`string`, required, date, example 2024-02-01) — Cancel the subscription on a specific date.
- `churn` (`enum<string>`, optional, one of 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) — Standardized reason for the cancellation used for reporting and analysis. If OTHER is provided, please also provide a comment.
- `comment` (`string`, optional, example Switching to a different provider) — Optional comment about the cancellation.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

Subscription cancellation scheduled successfully.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [POST /subscriptions/{subscriptionId}/suspend](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/suspend)

Suspend subscription

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `scheduledAt` (`string`, optional, date, example 2024-02-01) — Suspend the subscription on a specific date.
- `reason` (`string`, optional, example Payment overdue) — Optional reason for the suspension.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

Subscription suspension scheduled successfully.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [POST /subscriptions/{subscriptionId}/pause](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/pause)

Pause subscription

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

Subscription pause scheduled successfully.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [POST /subscriptions/{subscriptionId}/restore](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/restore)

Restore subscription

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `scheduledAt` (`string`, optional, date, example 2024-02-01) — Restore the subscription on a specific date.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

Subscription restoration scheduled successfully.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [POST /subscriptions/{subscriptionId}/block-sim](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/block-sim)

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 412

A precondition for this request was not met.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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'
```

## [POST /subscriptions/{subscriptionId}/change-sim](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/change-sim)

Change subscription SIM card

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

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max 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.

### Request body (required)

Type: `object`

- `scheduledAt` (`string`, optional, date, example 2024-02-01) — Change the SIM card on a specific date.
- `icc` (`string`, required, example 89012345678901234567) — 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.
- `simCardType` (`enum<string>`, required, one of PHYSICAL, ESIM, example PHYSICAL) — The type of SIM card being installed.
- `metadata` (`object with string keys`, optional) — 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.
  - `*` (`string`, optional)

### Responses

#### 200

SIM card change scheduled successfully.

Type: [Subscription](/api-reference/models.md#models/Subscription)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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"
  }
}'
```

## [GET /subscriptions/{subscriptionId}/esim/qrcode](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/esim/qrcode)

Get eSIM QR code

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.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

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

### Responses

#### 200

eSIM QR code data and hosted URL retrieved successfully.

Type: [EsimQrCode](/api-reference/models.md#models/EsimQrCode)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
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'
```