--- title: Subscriptions description: The subscriptions of the user, and the SIM operations on them. --- # Subscriptions The subscriptions of the user, and the SIM operations on them. ## [GET /subscriptions](/end-user-api/subscriptions#tag/subscriptions/GET/subscriptions) List subscriptions List all subscriptions. Will return all subscriptions the requester has access to. Authentication: X-Api-Key + Bearer JWT ### 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) - `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. - `barReasons` (`array of BarReason`, optional) — The reasons of the bars that keep a `BLOCKED` subscription blocked. A subscription can have more than one bar, and it stays blocked until every bar is removed. Present only while the status is `BLOCKED`. - `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. - `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. - `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. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields provided for custom subscription types. - `*` (`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) - `msisdn` (`string`, required, phone, personal data, 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. - `pendingMsisdn` (`object`, optional, personal data) — 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, personal data, 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. - `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. - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `group` (`object`, optional) — A product group organizes related product offerings. - `category` (`enum`, 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_SUBSCRIPTION_CELL_FIXED, PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD, PRODUCT_CATEGORY_VANITY_NUMBER_CELL, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_ABROAD_EXTRA_DATA, PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU, PRODUCT_CATEGORY_NETWORK_EXTENSIONS, PRODUCT_CATEGORY_VANITY_NUMBER, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, PRODUCT_CATEGORY_PBX_USER_LEVEL, PRODUCT_CATEGORY_PBX_NUMBER, PRODUCT_CATEGORY_PBX_MOBILE_NUMBER, PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD, PRODUCT_CATEGORY_PBX_SOFTPHONE, PRODUCT_CATEGORY_PBX_STATISTICS, PRODUCT_CATEGORY_PBX_CALL_RECORDING, PRODUCT_CATEGORY_PBX_VOICEMAIL, PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS, PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL, PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER, 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_CELL_FIXED` - Cellular subscription at a fixed location - `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 - `PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD` - Vanity number that forwards calls - `PRODUCT_CATEGORY_VANITY_NUMBER_CELL` - Vanity number on a cellular subscription **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 - `PRODUCT_CATEGORY_ABROAD_EXTRA_DATA` - Additional data package for roaming - `PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU` - Data package for use outside the EU - `PRODUCT_CATEGORY_NETWORK_EXTENSIONS` - Network feature addon - `PRODUCT_CATEGORY_VANITY_NUMBER` - Vanity number 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 **LICENSE categories (PBX):** - `PRODUCT_CATEGORY_PBX_USER_LEVEL` - Level of a PBX user license - `PRODUCT_CATEGORY_PBX_NUMBER` - PBX phone number - `PRODUCT_CATEGORY_PBX_MOBILE_NUMBER` - PBX mobile number - `PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD` - Forward from a landline number - `PRODUCT_CATEGORY_PBX_SOFTPHONE` - Softphone - `PRODUCT_CATEGORY_PBX_STATISTICS` - Call statistics - `PRODUCT_CATEGORY_PBX_CALL_RECORDING` - Call recording - `PRODUCT_CATEGORY_PBX_VOICEMAIL` - Voicemail - `PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS` - Queue capacity - `PRODUCT_CATEGORY_PBX_ROUTE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_QUEUE` - Call routes - `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL` - Call route features **Other categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER`, `PRODUCT_CATEGORY_INTERNATIONAL_NUMBER` A caller must tolerate new values. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `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. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `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. - `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`, 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. - `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. - `source` (`enum`, 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. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, 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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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) - `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`, 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. - `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. - `source` (`enum`, 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. - `includesTax` (`boolean`, optional, example false) — True when the configured price includes its tax. The tax is then a part of `netPriceMinor` rather than an amount on top of it. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `priceType` (`enum`, 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). - `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`, 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. - `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. - `source` (`enum`, 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. - `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. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering 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. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `status` (`enum`, 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 - `porting` (`object`, optional) — Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. - `direction` (`enum`, 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. - `msisdn` (`string`, required, personal data, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur. - `status` (`enum`, 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 - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `group` (`object`, optional) — A product group organizes related product offerings. - `category` (`enum`, 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_SUBSCRIPTION_CELL_FIXED, PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD, PRODUCT_CATEGORY_VANITY_NUMBER_CELL, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_ABROAD_EXTRA_DATA, PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU, PRODUCT_CATEGORY_NETWORK_EXTENSIONS, PRODUCT_CATEGORY_VANITY_NUMBER, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, PRODUCT_CATEGORY_PBX_USER_LEVEL, PRODUCT_CATEGORY_PBX_NUMBER, PRODUCT_CATEGORY_PBX_MOBILE_NUMBER, PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD, PRODUCT_CATEGORY_PBX_SOFTPHONE, PRODUCT_CATEGORY_PBX_STATISTICS, PRODUCT_CATEGORY_PBX_CALL_RECORDING, PRODUCT_CATEGORY_PBX_VOICEMAIL, PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS, PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL, PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER, 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_CELL_FIXED` - Cellular subscription at a fixed location - `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 - `PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD` - Vanity number that forwards calls - `PRODUCT_CATEGORY_VANITY_NUMBER_CELL` - Vanity number on a cellular subscription **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 - `PRODUCT_CATEGORY_ABROAD_EXTRA_DATA` - Additional data package for roaming - `PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU` - Data package for use outside the EU - `PRODUCT_CATEGORY_NETWORK_EXTENSIONS` - Network feature addon - `PRODUCT_CATEGORY_VANITY_NUMBER` - Vanity number 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 **LICENSE categories (PBX):** - `PRODUCT_CATEGORY_PBX_USER_LEVEL` - Level of a PBX user license - `PRODUCT_CATEGORY_PBX_NUMBER` - PBX phone number - `PRODUCT_CATEGORY_PBX_MOBILE_NUMBER` - PBX mobile number - `PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD` - Forward from a landline number - `PRODUCT_CATEGORY_PBX_SOFTPHONE` - Softphone - `PRODUCT_CATEGORY_PBX_STATISTICS` - Call statistics - `PRODUCT_CATEGORY_PBX_CALL_RECORDING` - Call recording - `PRODUCT_CATEGORY_PBX_VOICEMAIL` - Voicemail - `PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS` - Queue capacity - `PRODUCT_CATEGORY_PBX_ROUTE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_QUEUE` - Call routes - `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL` - Call route features **Other categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER`, `PRODUCT_CATEGORY_INTERNATIONAL_NUMBER` A caller must tolerate new values. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `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. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `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. - `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`, 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. - `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. - `source` (`enum`, 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. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, 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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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) - `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`, 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. - `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. - `source` (`enum`, 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. - `includesTax` (`boolean`, optional, example false) — True when the configured price includes its tax. The tax is then a part of `netPriceMinor` rather than an amount on top of it. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `priceType` (`enum`, 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). - `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`, 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. - `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. - `source` (`enum`, 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. - `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. - `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. - `serviceAddress` (`object`, optional) — The address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none. Absent when no record holds an address. — The address where a subscription is served, and the record that holds it. In the US, this is the E911 address that emergency services get for the phone number. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `source` (`enum`, required, one of SUBSCRIPTION, CUSTOMER_BILLING, example SUBSCRIPTION) — The record that holds the address. - `SUBSCRIPTION`: The subscription holds an address of its own. - `CUSTOMER_BILLING`: The subscription holds no address of its own, so the billing address of the customer applies. - `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. - `iccid` (`string`, optional, personal data, example 8901240197155182976) — Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware. Only applicable for eSIM. - `status` (`enum`, 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 - `subscriber` (`object`, optional) — The person who uses the service on a subscription, as distinct from the customer who pays for it. - `address` (`object`, optional, deprecated) — Deprecated. Use `serviceAddress` on the subscription instead. The service address of the subscription that embeds this subscriber. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The subscriber's email address, if one has been provided. - `name` (`string`, required, example John Doe) — The subscriber's full name. - `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. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `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. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated. - `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](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [GET /subscriptions/{subscriptionId}](/end-user-api/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}) Get subscription Retrieve detailed information about a specific subscription using its unique identifier. Authentication: X-Api-Key + Bearer JWT ### 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](/end-user-api/models.md#models/Subscription) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /subscriptions/{subscriptionId}/block-sim](/end-user-api/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/block-sim) Block subscription SIM Block the SIM card on one subscription of the customer of the user that makes the request, so it can no longer use the network. Use this when the user 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 user their number. A block is permanent for the user. `restoreSubscription` does not reverse it, because only a new SIM card brings the subscription back into service. The End-User API does not issue a SIM card, so the user must speak to the operator. Authentication: X-Api-Key + Bearer JWT ### 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](/end-user-api/models.md#models/Subscription) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/block-sim \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [GET /subscriptions/{subscriptionId}/esim/profile](/end-user-api/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/esim/profile) Get eSIM profile status Retrieve the live eSIM profile status for a subscription's SIM, reported by the network operator. Only available for eSIM subscriptions (`sim.esim: true`) that already have a SIM assigned. When the network operator reports no live status, the response still carries a profile object with `status: UNAVAILABLE` rather than an error, so a caller can tell "the operator gave nothing" apart from "there is no eSIM to ask about". When the network operator does not answer, the response is `503`, and the same request can succeed later. Authentication: X-Api-Key + Bearer JWT ### 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 profile status retrieved successfully. Type: [SubscriptionEsimProfile](/end-user-api/models.md#models/SubscriptionEsimProfile) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) #### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/profile \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [GET /subscriptions/{subscriptionId}/esim/qrcode](/end-user-api/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 + Bearer JWT ### 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](/end-user-api/models.md#models/EsimQrCode) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/qrcode \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /subscriptions/{subscriptionId}/pause](/end-user-api/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 + Bearer JWT ### 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` - `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) - `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. ### Responses #### 200 Subscription pause scheduled successfully. Type: [Subscription](/end-user-api/models.md#models/Subscription) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/pause \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "metadata": { "propertyName": "string" }, "scheduledAt": "2024-02-01" }' ``` ## [GET /subscriptions/{subscriptionId}/product-offering-options](/end-user-api/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. A product catalog can limit the product offerings that an offering change can move to. If a catalog of the customer does that, the options hold only product offerings of that list. Authentication: X-Api-Key + Bearer JWT ### 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) - `changeSchedule` (`enum`, required, one of INSTANT, FIRST_OF_NEXT_MONTH, NEXT_RENEWAL_DAY, NEXT_PAYMENT_DAY, END_OF_PAID_PERIOD, END_OF_BINDING_PERIOD) — The schedule type for when a product offering change can take effect. - INSTANT: The change takes effect at once - FIRST_OF_NEXT_MONTH: The change takes effect on the first day of the next calendar month - NEXT_RENEWAL_DAY: The change takes effect on the next renewal date - NEXT_PAYMENT_DAY: The change takes effect on the next payment day, when the days already paid for run out - END_OF_PAID_PERIOD: The change takes effect the day after the current paid period ends - END_OF_BINDING_PERIOD: The change takes effect the day after the binding period ends - `changeScheduleDate` (`string`, required, date, example 2024-02-01) — The date when the product offering change can take effect. - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `group` (`object`, optional) — A product group organizes related product offerings. - `category` (`enum`, 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_SUBSCRIPTION_CELL_FIXED, PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD, PRODUCT_CATEGORY_VANITY_NUMBER_CELL, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_ABROAD_EXTRA_DATA, PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU, PRODUCT_CATEGORY_NETWORK_EXTENSIONS, PRODUCT_CATEGORY_VANITY_NUMBER, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, PRODUCT_CATEGORY_PBX_USER_LEVEL, PRODUCT_CATEGORY_PBX_NUMBER, PRODUCT_CATEGORY_PBX_MOBILE_NUMBER, PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD, PRODUCT_CATEGORY_PBX_SOFTPHONE, PRODUCT_CATEGORY_PBX_STATISTICS, PRODUCT_CATEGORY_PBX_CALL_RECORDING, PRODUCT_CATEGORY_PBX_VOICEMAIL, PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS, PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL, PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER, 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_CELL_FIXED` - Cellular subscription at a fixed location - `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 - `PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD` - Vanity number that forwards calls - `PRODUCT_CATEGORY_VANITY_NUMBER_CELL` - Vanity number on a cellular subscription **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 - `PRODUCT_CATEGORY_ABROAD_EXTRA_DATA` - Additional data package for roaming - `PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU` - Data package for use outside the EU - `PRODUCT_CATEGORY_NETWORK_EXTENSIONS` - Network feature addon - `PRODUCT_CATEGORY_VANITY_NUMBER` - Vanity number 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 **LICENSE categories (PBX):** - `PRODUCT_CATEGORY_PBX_USER_LEVEL` - Level of a PBX user license - `PRODUCT_CATEGORY_PBX_NUMBER` - PBX phone number - `PRODUCT_CATEGORY_PBX_MOBILE_NUMBER` - PBX mobile number - `PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD` - Forward from a landline number - `PRODUCT_CATEGORY_PBX_SOFTPHONE` - Softphone - `PRODUCT_CATEGORY_PBX_STATISTICS` - Call statistics - `PRODUCT_CATEGORY_PBX_CALL_RECORDING` - Call recording - `PRODUCT_CATEGORY_PBX_VOICEMAIL` - Voicemail - `PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS` - Queue capacity - `PRODUCT_CATEGORY_PBX_ROUTE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_QUEUE` - Call routes - `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE`, `PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL` - Call route features **Other categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER`, `PRODUCT_CATEGORY_INTERNATIONAL_NUMBER` A caller must tolerate new values. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `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. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `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. - `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`, 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. - `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. - `source` (`enum`, 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. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, 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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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) - `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`, 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. - `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. - `source` (`enum`, 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. - `includesTax` (`boolean`, optional, example false) — True when the configured price includes its tax. The tax is then a part of `netPriceMinor` rather than an amount on top of it. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `priceType` (`enum`, 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). - `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`, 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. - `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. - `source` (`enum`, 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. - `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. #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/product-offering-options \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /subscriptions/{subscriptionId}/reset-network-services](/end-user-api/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/reset-network-services) Reset subscription network services Start the platform's provider-specific network-services reset for an activated subscription. The operation may briefly interrupt service, so `confirmed` must be true. A pending or running reset is returned instead of starting another one. A successful or failed reset completed during the previous 15 minutes is also returned, so an immediate retry is safe. Two requests that arrive at the same time usually return the same reset. In rare cases, each request returns a new reset. Then only the first reset changes the network, and the other reset fails without a change to the network. The reset does not change Seamless OS barring, add-ons, data buckets, or other commercial configuration. The provider workflow can suspend, reconnect, or recreate network-side state. On some networks, this can change the network-side data balance or shared data group. This operation is disabled by default. A deployment must set `FEATURE_END_USER_RESET_NETWORK_SERVICES=true` to make it available. A disabled deployment returns `501 Not Implemented` and starts no reset. Enable the operation only when the customer accepts the provider-specific risks. Authentication: X-Api-Key + Bearer JWT ### 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` - `confirmed` (`boolean`, required, example true) — Must be true after the user explicitly approves the temporary service interruption. ### Responses #### 200 Reset started, already running, or recently completed. Type: [ResetNetworkServicesResult](/end-user-api/models.md#models/ResetNetworkServicesResult) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) #### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/reset-network-services \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "confirmed": true }' ``` ## [POST /subscriptions/{subscriptionId}/restore](/end-user-api/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/restore) Restore subscription Restore a paused subscription of the customer of the user that makes the request back to the active state. The user can reverse only a pause that the user made. An operator suspends a subscription for non-payment or for fraud, and this operation does not reverse that suspension. You can schedule the restoration: - Immediate restore - Next day restoration - Beginning of next month restoration - Specific date restoration Authentication: X-Api-Key + Bearer JWT ### 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` - `allowedCurrentStatuses` (`array of SubscriptionStatus`, optional) — Current statuses from which this request can restore the subscription. If omitted, the request can restore all supported statuses. - `barReasons` (`array of BarReason`, optional, min items 1) — The reasons of the bars to remove from a `BLOCKED` subscription. The `barReasons` field of the subscription lists them. The subscription is activated only when no other bar stays. Otherwise it stays `BLOCKED` with the bars that stay. If omitted, the request removes every bar. If the subscription has no bar with one of these reasons, the request fails with `412`. - `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) - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Restore the subscription on a specific date. ### Responses #### 200 Subscription restoration scheduled successfully. Type: [Subscription](/end-user-api/models.md#models/Subscription) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/restore \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "allowedCurrentStatuses": [ "PENDING" ], "barReasons": [ "MISSING_PAYMENT" ], "metadata": { "propertyName": "string" }, "scheduledAt": "2024-02-01" }' ``` ## [GET /subscriptions/{subscriptionId}/roaming-cost-control](/end-user-api/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/roaming-cost-control) Get roaming cost control Get the roaming cost-control setting and current cost limit for a subscription. This operation does not return roaming allowances or top-up balances. Authentication: X-Api-Key + Bearer JWT ### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. The value can be an internal UUID or an external reference identifier with the `rid_` prefix. ### Responses #### 200 The roaming cost-control setting, including an explicit unsupported state. Type: [RoamingCostControl](/end-user-api/models.md#models/RoamingCostControl) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/roaming-cost-control \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [PUT /subscriptions/{subscriptionId}/service-address](/end-user-api/subscriptions#tag/subscriptions/PUT/subscriptions/{subscriptionId}/service-address) Change subscription service address Change the address where a subscription is served. In the US, this is the E911 address that emergency services get for the phone number. The subscription holds an address only when it is different from the billing address of the customer. An address that is equal to the billing address removes the address that the subscription holds. For an activated subscription, the platform sends the address to the network operator first. `serviceAddress` on the subscription shows the new address after the operator accepts it. Authentication: X-Api-Key + Bearer JWT ### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. The value can be an internal UUID or an external reference identifier with the `rid_` prefix. ### 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` - `address` (`object`, required) — The address where the subscriber uses this subscription. An address that is equal to the billing address of the customer removes the address that the subscription holds. The subscription then takes the billing address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. ### Responses #### 200 The subscription. An activated subscription shows the new address after the network operator accepts it. Type: [Subscription](/end-user-api/models.md#models/Subscription) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/service-address \ --request PUT \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" } }' ``` ## [GET /subscriptions/{subscriptionId}/us-port-out-pin](/end-user-api/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/us-port-out-pin) Get the US port-out PIN Get the active port-out PIN of a subscription and whether the subscription can port out. A subscription that cannot port out, for example during a binding period or with a leased custom number, has `portable` false and no PIN. A new number in its port-out protection period has `portOutProtection`, which gives the first day that a new carrier can port out the number. Only US brands support this operation. Other brands return `501 Not Implemented`. Authentication: X-Api-Key + Bearer JWT ### 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 The port-out state of the subscription. Type: [USPortOutPinState](/end-user-api/models.md#models/USPortOutPinState) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) #### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /subscriptions/{subscriptionId}/us-port-out-pin](/end-user-api/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/us-port-out-pin) Generate a US port-out PIN Generate a new PIN that the subscriber gives to a new carrier to move the number away from this subscription. The PIN is valid for 7 days. The previous PIN of the subscription stops working when you generate a new one. A subscription that cannot port out, for example during a binding period or with a leased custom number, returns `412 Precondition Failed`. Only US brands support this operation. Other brands return `501 Not Implemented`. Authentication: X-Api-Key + Bearer JWT ### 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 The new PIN. Type: [USPortOutPin](/end-user-api/models.md#models/USPortOutPin) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) #### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ```