--- title: Schemas description: Every request, response and webhook payload schema in the API. --- # Schemas Every request, response and webhook payload schema in the API. ## [AddLineItemRequest](/end-user-api/models#models/AddLineItemRequest) Request to add a line item to an order. Type: `object` - `lineItem` (`one of`, required) — A line item in an order representing a billable action or service. - One of: `SUBSCRIPTION` - `activateOnDemand` (`boolean`, optional, example true) — Whether the subscription waits for the subscriber to activate it rather than being activated on a date. The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time. Cannot be combined with scheduleActivationAt. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `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`, optional, personal data, example +15551234567) — The phone number for this subscription. - Leave empty to have one assigned. - When the number pool is available, you can choose a number from the pool and provide the leaseToken. - When porting a number, provide the number and porting details. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `sim` (`object`, optional) — The choice between eSIM and physical SIM plus related device details. This value is optional while the order is a draft. You must give it before you submit the order. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriber` (`object`, optional) — The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at 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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `tempNumber` (`boolean`, optional, example true) — Whether to use a temporary number until the porting is completed. If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized. Can only be used when porting in a number (i.e., when msisdn and porting details are provided). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - One of: `SUBSCRIPTION_CHANGE` - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription. The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `simChange` (`object`, optional) — The SIM card change. Give this value only for changeType SIM_CHANGE. — A change of the SIM card of a subscription. The change carries a one-time price. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. ## [AddonChangeLineItem](/end-user-api/models#models/AddonChangeLineItem) Line item that changes an add-on of a subscription. The changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item. Type: `object` - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. ## [AddonLineItem](/end-user-api/models#models/AddonLineItem) Line item for adding an add-on to a subscription. Type: `object` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. ## [AddonPlanChange](/end-user-api/models#models/AddonPlanChange) A change of the product of an add-on. Type: `object` - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. ## [Address](/end-user-api/models#models/Address) A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. Type: `object` - `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. ## [AddressValidationResult](/end-user-api/models#models/AddressValidationResult) Result of address validation with optional suggestions. Depending on setup, address validation is either shape based (e.g. this looks like an address), or verified against an address registry. Type: `object` - `suggestedAddress` (`object`, optional) — If provided, a suggestion for a corrected address by the underlying address validation service. Do note that this may be returned for seemingly valid addresses, where the network has a more precise or standardized version of the address. A typical example of this is the address is found in the networks' registry but under a different name because it contains aliases or minor formatting issues, mistyped zip codes, etc. — 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. - `valid` (`boolean`, required, example false) — Whether the provided address is valid. - `validationDetails` (`object`, optional, example {"issues":[{"message":"Missing city","property":"city"},{"message":"Invalid zip format","property":"zip"}]}) — Additional validation details. - `issues` (`array of object`, optional) — Specific issues found with the address. - `message` (`string`, required, example Missing city) — Description of the issue found. - `property` (`string`, optional, example city) — The property or field related to the issue (e.g., "street", "zipCode"). ## [Any](/end-user-api/models#models/Any) A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for. Type: `one of` - One of: `string` - One of: `number` - One of: `boolean` - One of: `object` - `propertyName` (`any`, optional) — Any additional properties, passed through as given. - One of: `array of any` ## [BarReason](/end-user-api/models#models/BarReason) Why a subscription is barred. The reason tells what removes the bar. - UNKNOWN: The bar has no recorded reason. - NEW_SIM_CARD: The SIM card is blocked, for example after a lost or stolen phone. A new SIM card removes the bar. - MISSING_PAYMENT: A payment is missing. The payment removes the bar. - FRAUD: The fraud check barred the subscription. - CUSTOMER_BLOCKED: The customer of the subscription is blocked. An unblock of the customer removes the bar. - MANUAL: An operator barred the subscription by hand. Type: `enum` ## [BillingCycle](/end-user-api/models#models/BillingCycle) How often a recurring price is charged. Type: `object` - `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](/end-user-api/models#models/BindingContract) A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. Type: `object` - `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. ## [BroadbandFacts](/end-user-api/models#models/BroadbandFacts) The values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price. Type: `object` - `additionalDataIncrementGb` (`number`, required, example 0) — The amount of data, in GB, that `overUsageDataPriceMinor` buys. Always 0, because the platform sells no data after the allowance. - `earlyTerminationFeeMinor` (`integer`, required, int64, example 0) — The fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee. - `monthlyProviderFees` (`array of BroadbandFactsFee`, required) — The fees that the provider adds to the monthly price. - `amountMinor` (`integer`, required, int64, example 21) — The amount of the fee, in minor currency units. - `name` (`string`, required, example Federal Universal Service Fund) — What the label calls the fee. - `overUsageDataPriceMinor` (`integer`, required, int64, example 0) — The price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price. - `planCode` (`string`, required, example FLEXSTANDARD001) — 15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan identifier on the label is `M`, then the FCC Registration Number of the brand, then this code. - `singlePurchaseFees` (`array of BroadbandFactsFee`, required) — The fees that the customer pays one time, when they buy the plan. - `amountMinor` (`integer`, required, int64, example 21) — The amount of the fee, in minor currency units. - `name` (`string`, required, example Federal Universal Service Fund) — What the label calls the fee. - `unlimitedData` (`boolean`, required, example false) — True when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product. ## [BroadbandFactsFee](/end-user-api/models#models/BroadbandFactsFee) One fee on the FCC Broadband Facts label. Type: `object` - `amountMinor` (`integer`, required, int64, example 21) — The amount of the fee, in minor currency units. - `name` (`string`, required, example Federal Universal Service Fund) — What the label calls the fee. ## [CancelPaymentSessionRequest](/end-user-api/models#models/CancelPaymentSessionRequest) Request to cancel an active payment session. Type: `object` - `metadata` (`object with string keys`, optional, example {"cancelled_by":"customer_service","ticket_id":"SUPP-12345"}) — Custom key-value pairs for additional cancellation information. - `*` (`string`, optional) - `reason` (`string`, optional, example Customer changed their mind) — Optional reason for cancelling the payment session. ## [ChangeSubscriptionServiceAddressRequest](/end-user-api/models#models/ChangeSubscriptionServiceAddressRequest) Request to change the address where a subscription is served. 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. ## [CheckNetworkCoverageRequest](/end-user-api/models#models/CheckNetworkCoverageRequest) Request to check network coverage at a location. Type: `object` - `address` (`object`, required) — A location to check network coverage at. Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it. - `city` (`string`, optional, 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). - `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`, optional, 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. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). ## [CheckPortingEligibilityRequest](/end-user-api/models#models/CheckPortingEligibilityRequest) Request to check if a phone number is eligible for porting. Type: `object` - `msisdn` (`string`, required, phone, personal data, example +15551234567) — The phone number to check for porting eligibility. ## [Consents](/end-user-api/models#models/Consents) The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later. Type: `object with string keys` - `*` (`string`, optional) ## [Coordinates](/end-user-api/models#models/Coordinates) A geographic location in WGS84 coordinates, the standard used by GPS. Type: `object` - `latitude` (`number`, required, float, personal data, example 40.7128) — Latitude in decimal degrees. Positive values are north of the equator. - `longitude` (`number`, required, float, personal data, example -74.006) — Longitude in decimal degrees. Negative values are west of the prime meridian. ## [CoverageAddress](/end-user-api/models#models/CoverageAddress) A location to check network coverage at. Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it. Type: `object` - `city` (`string`, optional, 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). - `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`, optional, 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. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). ## [CreateOrderRequest](/end-user-api/models#models/CreateOrderRequest) Request to create a new order for a customer of the user that makes the request. You can create an order with the minimum data, then add the remainder of the data in subsequent requests. The bearer token supplies the user, so the request gives no user. A user can manage more than one customer, so the request names the customer that the order is for. Type: `object` - `billing` (`object`, optional) — Billing information for an order. For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level. - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no 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. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. - `consents` (`object with string keys`, optional, example {"marketing":"true","termsOfService":"true"}) — The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later. - `*` (`string`, optional) - `customer` (`one of`, optional) — Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer. - One of: `ExistingCustomerById` - `customerId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically. - One of: `AuthenticatedCustomer` - `authenticatedCustomer` (`boolean`, required, example true) — Always true. - One of: `OrderCustomerReference_NewCustomer` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — The type of customer this order is for. This scopes the order to the customer type's context, which affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it. For logged in orders, this must match the customer's type. - `lineItems` (`array of OrderLineItem`, optional) — Initial line items for the order (can be empty). - One of: `SUBSCRIPTION` - `activateOnDemand` (`boolean`, optional, example true) — Whether the subscription waits for the subscriber to activate it rather than being activated on a date. The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time. Cannot be combined with scheduleActivationAt. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `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`, optional, personal data, example +15551234567) — The phone number for this subscription. - Leave empty to have one assigned. - When the number pool is available, you can choose a number from the pool and provide the leaseToken. - When porting a number, provide the number and porting details. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `sim` (`object`, optional) — The choice between eSIM and physical SIM plus related device details. This value is optional while the order is a draft. You must give it before you submit the order. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriber` (`object`, optional) — The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at 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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `tempNumber` (`boolean`, optional, example true) — Whether to use a temporary number until the porting is completed. If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized. Can only be used when porting in a number (i.e., when msisdn and porting details are provided). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - One of: `SUBSCRIPTION_CHANGE` - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription. The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `simChange` (`object`, optional) — The SIM card change. Give this value only for changeType SIM_CHANGE. — A change of the SIM card of a subscription. The change carries a one-time price. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `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) - `promoCode` (`string`, optional, example SUMMER2023) — Promo code to apply to the order. Rejected with `internalCode` 4119 when no promotion has that code, or when it is outside its validity period. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. ## [CreatePaymentSessionRequest](/end-user-api/models#models/CreatePaymentSessionRequest) Request to create a new payment session for processing payment for an order. Type: `object` - `branding` (`object`, optional) — The colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form. - `backgroundColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #ffffff) — The background color of the payment form, as a hex value with a leading number sign. - `borderStyle` (`enum`, optional, one of PILL, RECTANGULAR, ROUNDED, example PILL) — The shape of the buttons and the input fields of the payment form. - `buttonColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #0cf68c) — The color of the payment button, as a hex value with a leading number sign. - `displayName` (`string`, optional, max length 100, example Seamless) — The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms. - `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only. - `grantAutopayConsent` (`boolean`, optional, example false) — Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false. - `hosted` (`boolean`, optional, example true) — Whether to collect the payment on a hosted page. A hosted session returns hostedUrl, and you send the customer to it. An embedded session (false) returns providerContext, and you show the payment form inside your own checkout page. Defaults to true. - `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) - `orderId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-89abcdef0123) — The unique identifier of the order to create a payment session for. - `paymentProfileId` (`string`, optional, example e5f6a7b8-c9d0-1234-5678-9abcdef01234) — A previously saved payment method to prefill on the payment page, for returning customers. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `returnUrl` (`string`, required, example https://example.com/order/confirmation) — The URL the customer comes back to after they pay. A hosted page redirects to it. An embedded form redirects to it only for a payment method that leaves the page, such as 3D Secure. Must be provided to create a session. - `savePaymentProfile` (`boolean`, optional, example true) — Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false. - `setAsDefaultPaymentProfile` (`boolean`, optional, example false) — Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false. ## [Currency](/end-user-api/models#models/Currency) The three-letter ISO 4217 code of the currency used for prices, billing, and payments. Type: `string` ## [Customer](/end-user-api/models#models/Customer) A customer is a billable entity, the person or organization responsible for paying for services. The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer. Type: `object` - `billing` (`object`, optional) — Billing configuration and payment preferences for the customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, default false, example true) — Whether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `defaultPaymentProfileId` (`string`, optional, example c1d2e3f4-a5b6-7890-1234-901234567890) — Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills. - `email` (`string`, optional, email, personal data, example billing@company.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, required) — Contact details for the customer. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — The primary contact phone number for the customer. - `contactPerson` (`object`, optional) — The primary contact person for the customer. — A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile. - `name` (`string`, required, example John Doe) — The user's full name. - `role` (`enum`, optional, one of MEMBER, MANAGER, ADMIN) — The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — Unique identifier for the customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `deliveryAddress` (`object`, optional) — The address that a delivery to this customer uses. It is `shippingAddress` when the customer holds one, and `billing.address` when the customer holds none. The platform resolves this field. To change it, change one of the two addresses. — 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. - `humanReadableId` (`string`, optional, example 29A-BY3Z-X78) — A human-readable identifier for the customer that customers can state in support requests. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `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. Shown on invoices and throughout the API. - `preferredLocale` (`string`, optional, default en-US, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation. - `shipping` (`object`, optional, deprecated) — Deprecated. Use `shippingAddress` instead. The shipping address for the customer. Only `address` holds a value. — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `shippingAddress` (`object`, optional) — The address where the customer gets physical goods, such as SIM cards or devices. Absent when the customer gave no shipping address. A delivery then goes to 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. - `users` (`array of EmbeddedCustomerUser`, optional) — The users associated with this customer, each with the role that governs what they can manage on the customer's account. - `name` (`string`, required, example John Doe) — The user's full name. - `role` (`enum`, optional, one of MEMBER, MANAGER, ADMIN) — The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. ## [CustomerBillingMethod](/end-user-api/models#models/CustomerBillingMethod) How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. Type: `enum` ## [CustomerType](/end-user-api/models#models/CustomerType) Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. Type: `enum` ## [DeviceInfo](/end-user-api/models#models/DeviceInfo) Information about a device based on its IMEI. Type: `object` - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `imei` (`string`, required, personal data, example 356938035643809) — The device IMEI that was checked. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. - `model` (`string`, optional, example A2653) — Device model. - `tac` (`string`, optional, example 35693803) — The device TAC (Type Allocation Code), which is the first 8 digits of the IMEI identifying the device model and manufacturer. ## [DeviceMatch](/end-user-api/models#models/DeviceMatch) A device the network knows by name. It carries no IMEI, because a name matches a model rather than one handset. Type: `object` - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. - `model` (`string`, optional, example A2653) — Device model. - `tac` (`string`, optional, example 35693803) — The device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer. ## [DeviceSearchResult](/end-user-api/models#models/DeviceSearchResult) The devices whose name matches the query. Type: `object` - `items` (`array of DeviceMatch`, required) — One entry per matching device. An empty list means the network knows no device by that name. - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. - `model` (`string`, optional, example A2653) — Device model. - `tac` (`string`, optional, example 35693803) — The device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer. ## [Duration](/end-user-api/models#models/Duration) A length of time, expressed as a count of some unit. Type: `object` - `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. ## [EmbeddedAssignedTo](/end-user-api/models#models/EmbeddedAssignedTo) The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription. Type: `object` - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment ## [EmbeddedCustomer](/end-user-api/models#models/EmbeddedCustomer) Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. Type: `object` - `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. ## [EmbeddedCustomerUser](/end-user-api/models#models/EmbeddedCustomerUser) A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile. Type: `object` - `name` (`string`, required, example John Doe) — The user's full name. - `role` (`enum`, optional, one of MEMBER, MANAGER, ADMIN) — The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. ## [EmbeddedLicense](/end-user-api/models#models/EmbeddedLicense) Essential license information without sensitive details. Type: `object` - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the license was activated. - `assignedTo` (`object`, required) — The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription. - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `customer` (`object`, optional) — 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. - `licenseId` (`string`, required, example b3c4d5e6-f7a8-9012-3456-789012345678) — The unique identifier for the license. - `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. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `type` (`string`, optional, example PBX_USER_LEVEL) — The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. ## [EmbeddedPorting](/end-user-api/models#models/EmbeddedPorting) Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. Type: `object` - `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 ## [EmbeddedProduct](/end-user-api/models#models/EmbeddedProduct) Embedded representation of a product. Type: `object` - `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. - `features` (`object`, optional) — The features included with the product, if any. Typically used for telecom products. - `activationType` (`enum`, optional, one of INSTANT, FIRST_USE, example INSTANT) — How the travel eSIM package activates. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `countries` (`array of string`, optional, example ["USA","CAN","MEX"]) — ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `countries` query parameter on list endpoints to filter by coverage. - `dataMb` (`number`, optional, example 2048) — Megabytes of data included with the product. Present for cellular, data, and travel eSIM products. - `includedCallSeconds` (`integer`, optional, example 1000) — Outbound call seconds included with the product. Present for cellular subscription categories. - `includedSms` (`integer`, optional, example 500) — Number of SMS messages included with the product. Present for cellular subscription categories. - `regions` (`array of string`, optional, example ["NORTH_AMERICA"]) — Named regions covered by the product. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `regions` query parameter on list endpoints to filter by coverage. - `simCardType` (`enum`, optional, one of PSIM, ESIM, example PSIM) — The SIM format for a SIM card product. - `validityDays` (`integer`, optional, example 30) — Number of days the product is valid for. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `internalName` (`string`, required, example us-mobile-unlimited-5gb) — The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead. - `networkProviderId` (`string`, optional, example tmobile-us) — The unique identifier for the network provider. - `productId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-890123456789) — The unique identifier for the product. - `type` (`enum`, required, one of SUBSCRIPTION, SUBSCRIPTION_ADDON, LICENSE, EXTERNAL_PRODUCT, SIM_CARD, example SUBSCRIPTION) — The type of product offering determines how it can be used and what kind of resource it creates. **SUBSCRIPTION** Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM). - Includes categories like `SUBSCRIPTION_CELL`, `TRAVEL_ESIM` - Can be created via order or directly depending on configuration - Has its own lifecycle (activation, suspension, termination) **SUBSCRIPTION_ADDON** Adds features or resources to an existing subscription. - Includes categories like `TRAVEL_ESIM_PACKAGE` - Must be attached to a parent subscription **LICENSE** Creates a license for business/PBX features. - Typically used for enterprise telephony features **EXTERNAL_PRODUCT** Represents purchasable items outside the core telecom platform. - Can only be ordered via orders, not created directly **SIM_CARD** Replaces the SIM card for an existing subscription through a subscription change order. ## [EmbeddedProductOffering](/end-user-api/models#models/EmbeddedProductOffering) Essential information about a product offering — what is being sold and at what price — without the full catalog details. Type: `object` - `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. ## [EmbeddedSubscriber](/end-user-api/models#models/EmbeddedSubscriber) The person who uses the service on a subscription, as distinct from the customer who pays for it. Type: `object` - `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. ## [Error](/end-user-api/models#models/Error) The error body returned by every endpoint when a request fails. Branch on `reason`, show `message` to a human, and check `details` for field-level problems when the request was invalid. Type: `object` - `code` (`string`, required, deprecated, example not_found) — Deprecated. Use `reason`. This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it. - `details` (`array of object`, optional) — Additional details about the error, typically one entry per invalid field on validation failures. - `code` (`string`, required, deprecated, example invalid_argument) — Deprecated. Use `reason`. It is the status of the whole error, the same for each item. - `message` (`string`, required, example Email format is invalid.) — A human-readable message providing more details about the error. - `property` (`string`, optional, example contact.email) — The property or field related to the error. May be nested using dot notation (e.g., "billing.email"). - `reason` (`string`, optional, example property_invalid) — Names the problem with the property. `property_required` is a missing value, `property_invalid` is a value with the wrong format, and `property_conflict` is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know. - `suggestion` (`one of`, optional) — A suggested value for the particular property. For example, this may be set when validating an address with an alias, suggesting the expected value by the operator. — A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for. - One of: `string` - One of: `number` - One of: `boolean` - One of: `object` - `propertyName` (`any`, optional) — Any additional properties, passed through as given. - One of: `array of any` - `domain` (`string`, optional, example address) — The business area of the reason, for example `customer` or `porting`. It is for information only. Do not branch on it. - `externalCode` (`string`, optional, example 3077) — The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it. - `externalSource` (`string`, optional, example Tele2) — The third party that reported the failure. - `hint` (`string`, optional, example Verify the customerId and try again.) — A hint to help resolve the error. - `internalCode` (`string`, optional, example 4009) — The number of the condition that failed. It is stable across releases. A condition that we added after `reason` has no number, so branch on `reason` instead. - `message` (`string`, required, example The requested customer could not be found.) — A human-readable message providing more details about the error. - `reason` (`string`, optional, example address_not_taxable) — Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know. If the request has problems with different reasons, the reason is `validation_failed`. Then each item of `details` names its own problem. - `retryable` (`boolean`, optional, example false) — True when the same request can pass later with no change. A `429` and a `503` are always retryable. - `spanId` (`string`, optional, example 37cec694d3b99f0f) — The span within the trace that failed. - `traceId` (`string`, optional, example cc4a73acca1bb07e0e54bd41f5ce1e7e) — Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served. ## [EsimInstallationStatus](/end-user-api/models#models/EsimInstallationStatus) The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator. Type: `enum` ## [EsimQrCode](/end-user-api/models#models/EsimQrCode) eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL. Type: `object` - `expiresAt` (`string`, optional, date-time, example 2024-12-31T23:59:59Z) — When the QR code and any hosted URL expire. After this time, a new QR code should be requested. Omitted when no expiry applies. - `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) - `qrCodeData` (`string`, required, example LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012) — The QR code data string that contains the eSIM profile download information (LPA format). - `qrCodeUrl` (`string`, optional, uri, example https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4) — Hosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription this QR code belongs to. ## [ExternalLineItem](/end-user-api/models#models/ExternalLineItem) Line item for selling an externally managed product or service that is not in the product catalog. You define the name, price, and taxation, and can optionally receive a webhook to fulfill the item yourself. Type: `object` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. ## [ExternalProductLineItem](/end-user-api/models#models/ExternalProductLineItem) Line item for purchasing a catalog product that is fulfilled outside the platform. The order records the sale while fulfillment happens in your own systems. Type: `object` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. ## [GetDeviceInfoRequest](/end-user-api/models#models/GetDeviceInfoRequest) Request to get device information by IMEI. Type: `object` - `imei` (`string`, required, personal data, example 356938035643809) — The International Mobile Equipment Identity of the device. ## [Identity](/end-user-api/models#models/Identity) A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. Type: `string` ## [InlineValidationError](/end-user-api/models#models/InlineValidationError) A single validation problem reported on an entity, explaining what must be corrected. For example, orders return these for anything that blocks submission. Type: `object` - `code` (`enum`, optional, deprecated, one of NOT_AN_INITIAL_OFFERING, ADDON_NOT_APPLICABLE, OFFERING_CHANGE_NOT_AVAILABLE, example NOT_AN_INITIAL_OFFERING) — Deprecated. Use `reason`. A code for the problem. An order sets it when the order cannot buy the product offering of a line item: - NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer. - ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on. - OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering. A problem without a code is a field that is missing or not correct. - `message` (`string`, required, example Subscriber name is required.) — Validation error message. - `property` (`string`, optional, example subscriber.name) — Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email"). - `reason` (`string`, optional, example not_an_initial_offering) — Names the problem. `property_required` is a missing value, `property_invalid` is a value with the wrong format, and `property_conflict` is two values that cannot occur together. Other reasons name a business condition, for example `not_an_initial_offering`. Your client must accept a reason that it does not know. ## [Invoice](/end-user-api/models#models/Invoice) An invoice used to collect a payment from a customer. The invoice records the provider's invoice lifecycle and balances; the related payment intent records what is being collected, its payment attempts, and any refunds. Type: `object` - `subtotalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read the related payment intent's line items instead. - `taxAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read the related payment intent's line-item taxes instead. - `feeAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The invoice projection has no separate fee total. - `discountAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read the related payment intent's line-item discounts instead. - `totalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read `amountDueMinor` instead. - `amountDueMinor` (`integer`, required, int64, example 3239) — The amount due when the invoice was issued, in minor units of the invoice currency. - `amountPaidMinor` (`integer`, required, int64, example 0) — The amount credited to the invoice, in minor units of the invoice currency. - `amountRemainingMinor` (`integer`, required, int64, example 3239) — The amount still unpaid, in minor units of the invoice currency. - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts. - `customerId` (`string`, required, example 456789ab-cdef-0123-4567-89abcdef0123) — The customer this invoice collects payment from. - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date. - `hostedUrl` (`string`, optional, uri, example https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000) — The provider-hosted page where the customer can view and pay the invoice. - `invoiceId` (`string`, required, example 123e4567-e89b-12d3-a456-426614174000) — Unique identifier for the invoice. - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft. - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one. - `sentAt` (`string`, optional, date-time, deprecated) — Deprecated. Read `issuedAt` instead. - `paidAt` (`string`, optional, date-time, example 2026-08-20T14:30:00Z) — When the invoice became paid. - `paymentIntent` (`object`, optional) — The payment intent associated with this invoice, including payment attempts and refunds. This field is absent for invoices that do not have a related payment intent. — The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items. A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice. - `amountMinor` (`integer`, required, int64, example 2900) — The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `attempts` (`array of PaymentAttempt`, required) — Charge attempts made against this payment intent, most recent first. - `amountMinor` (`integer`, required, int64, example 2900) — The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `chargedAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the charge was made. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the attempt was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `description` (`string`, optional, example Mobile subscription renewal) — A human-readable description of what is being collected. - `discounts` (`array of PaymentIntentDiscount`, required) — Reductions applied to the payment intent as a whole rather than to one billed line. - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. - `dueAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the amount is due. - `lineItems` (`array of PaymentIntentLineItem`, required) — The items that make up the collected amount. - `amountMinor` (`integer`, required, int64, example 2900) — The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless `includesTax` is true and they are a part of it. - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `refunds` (`array of PaymentRefund`, required) — Refunds issued against this payment intent. - `amountMinor` (`integer`, required, int64, example 2900) — The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the refund is issued in (e.g., "USD"). - `reason` (`enum`, optional, one of UNKNOWN, DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, DISPUTE_LOST, example REQUESTED_BY_CUSTOMER) — Why the refund was issued. - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. - `status` (`enum`, required, one of UNKNOWN, PENDING, REQUIRES_ACTION, PROCESSING, SUCCEEDED, REQUIRES_PAYMENT_METHOD, CANCELED, example SUCCEEDED) — Current stage of a payment intent as it is collected through the payment provider. - UNKNOWN: The platform has no supported mapping for the current provider state. - PENDING: Created, no charge attempted yet. - REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication). - PROCESSING: A charge is in flight with the payment provider. - SUCCEEDED: The full amount has been collected. - REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry. - CANCELED: Collection was canceled and no further charges will be attempted. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The provider that issued and manages the invoice. — Payment service provider that processes the transaction. - `invoiceUrl` (`string`, optional, uri, deprecated) — Deprecated. Read `hostedUrl` instead. - `pdfUrl` (`string`, optional, uri, example https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000.pdf) — Direct URL to the provider-generated invoice PDF. - `lineItems` (`array of InvoiceLineItem`, required, deprecated) — Deprecated. Read `paymentIntent.lineItems` instead. - `description` (`string`, required, example Mobile subscription - Premium Plan) — Description of what this line item represents. - `discounts` (`array of object`, optional) — Detailed discount breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 500) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example Volume discount) — Discount name or description. - `fees` (`array of object`, optional) — Detailed fee breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 1000) — Fee amount, in minor currency units. - `name` (`string`, required, example Late payment fee) — Fee name or description. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — ID of the license this line item is associated with, if applicable. - `productOfferingId` (`string`, optional, example mobile-plan-premium) — ID of the product offering this line item is associated with, if applicable. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of items for this line item. - `subscriptionId` (`string`, optional, example b8174435-6378-4be5-a9f5-8b4aaadae5d4) — ID of the subscription this line item is associated with, if applicable. - `subtotalMinor` (`integer`, required, int64, example 2999) — Line item subtotal (quantity x unitPriceMinor), in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Total taxes for this line item, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — Tax breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. - `taxIncluded` (`boolean`, optional, example false) — Whether taxes are included in the total. - `totalDiscountsMinor` (`integer`, optional, int64, example 500) — Total discounts for this line item, in minor currency units. - `totalFeesMinor` (`integer`, optional, int64, example 1000) — Total fees for this line item, in minor currency units. - `totalMinor` (`integer`, required, int64, example 3739) — Line item total after taxes, fees, and discounts, in minor currency units. - `unitPriceMinor` (`integer`, optional, int64, example 2999) — Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD). - `invoiceNumber` (`string`, required, deprecated) — Deprecated. Read `number` instead. - `status` (`enum`, required, one of UNKNOWN, DRAFT, ISSUED, SENT, PARTIALLY_PAID, PAID, OVERDUE, UNCOLLECTIBLE, VOID, CREDITED) — Current status of the invoice. — Current stage of the invoice lifecycle. - UNKNOWN: The provider status could not be mapped. - DRAFT: The invoice has not been issued. - ISSUED: The provider issued the invoice and it is awaiting payment. - SENT: Deprecated alias accepted in status filters. Responses use ISSUED. - PARTIALLY_PAID: Some, but not all, of the amount due has been paid. - PAID: The invoice has been paid. - OVERDUE: The invoice is past its due date and remains unpaid. - UNCOLLECTIBLE: The provider no longer expects to collect the invoice. - VOID: The invoice was canceled and is no longer collectible. - CREDITED: The invoice was settled by credit. - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated. - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided. - `metadata` (`object with string keys`, optional, deprecated) — Deprecated. Invoice metadata is not stored by the platform. — 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) ## [InvoiceLineItem](/end-user-api/models#models/InvoiceLineItem) Individual line item within an invoice, showing detailed pricing breakdown. Type: `object` - `description` (`string`, required, example Mobile subscription - Premium Plan) — Description of what this line item represents. - `discounts` (`array of object`, optional) — Detailed discount breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 500) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example Volume discount) — Discount name or description. - `fees` (`array of object`, optional) — Detailed fee breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 1000) — Fee amount, in minor currency units. - `name` (`string`, required, example Late payment fee) — Fee name or description. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — ID of the license this line item is associated with, if applicable. - `productOfferingId` (`string`, optional, example mobile-plan-premium) — ID of the product offering this line item is associated with, if applicable. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of items for this line item. - `subscriptionId` (`string`, optional, example b8174435-6378-4be5-a9f5-8b4aaadae5d4) — ID of the subscription this line item is associated with, if applicable. - `subtotalMinor` (`integer`, required, int64, example 2999) — Line item subtotal (quantity x unitPriceMinor), in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Total taxes for this line item, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — Tax breakdown for this line item. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. - `taxIncluded` (`boolean`, optional, example false) — Whether taxes are included in the total. - `totalDiscountsMinor` (`integer`, optional, int64, example 500) — Total discounts for this line item, in minor currency units. - `totalFeesMinor` (`integer`, optional, int64, example 1000) — Total fees for this line item, in minor currency units. - `totalMinor` (`integer`, required, int64, example 3739) — Line item total after taxes, fees, and discounts, in minor currency units. - `unitPriceMinor` (`integer`, optional, int64, example 2999) — Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD). ## [InvoiceListItem](/end-user-api/models#models/InvoiceListItem) An invoice summary. Get the invoice to read its related payment intent, payment attempts, and refunds. Type: `object` - `subtotalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Get the invoice and read its related payment intent instead. - `totalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read `amountDueMinor` instead. - `amountDueMinor` (`integer`, required, int64, example 3239) — The amount due when the invoice was issued, in minor units of the invoice currency. - `amountPaidMinor` (`integer`, required, int64, example 0) — The amount credited to the invoice, in minor units of the invoice currency. - `amountRemainingMinor` (`integer`, required, int64, example 3239) — The amount still unpaid, in minor units of the invoice currency. - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts. - `customerId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer this invoice collects payment from. - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date. - `hostedUrl` (`string`, optional, uri, example https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d) — The provider-hosted page where the customer can view and pay the invoice. - `invoiceId` (`string`, required, example 094f10ca-616e-441c-b264-9a2305d6692d) — Unique identifier for the invoice. - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft. - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one. - `sentAt` (`string`, optional, date-time, deprecated) — Deprecated. Read `issuedAt` instead. - `paidAt` (`string`, optional, date-time, example 2026-08-20T14:30:00Z) — When the invoice became paid. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The provider that issued and manages the invoice. — Payment service provider that processes the transaction. - `invoiceUrl` (`string`, optional, uri, deprecated) — Deprecated. Read `hostedUrl` instead. - `pdfUrl` (`string`, optional, uri, example https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d.pdf) — Direct URL to the provider-generated invoice PDF. - `invoiceNumber` (`string`, required, deprecated) — Deprecated. Read `number` instead. - `status` (`enum`, required, one of UNKNOWN, DRAFT, ISSUED, SENT, PARTIALLY_PAID, PAID, OVERDUE, UNCOLLECTIBLE, VOID, CREDITED) — Current status of the invoice. — Current stage of the invoice lifecycle. - UNKNOWN: The provider status could not be mapped. - DRAFT: The invoice has not been issued. - ISSUED: The provider issued the invoice and it is awaiting payment. - SENT: Deprecated alias accepted in status filters. Responses use ISSUED. - PARTIALLY_PAID: Some, but not all, of the amount due has been paid. - PAID: The invoice has been paid. - OVERDUE: The invoice is past its due date and remains unpaid. - UNCOLLECTIBLE: The provider no longer expects to collect the invoice. - VOID: The invoice was canceled and is no longer collectible. - CREDITED: The invoice was settled by credit. - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated. - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided. - `metadata` (`object with string keys`, optional, deprecated) — Deprecated. Invoice metadata is not stored by the platform. — 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) ## [InvoiceStatus](/end-user-api/models#models/InvoiceStatus) Current stage of the invoice lifecycle. - UNKNOWN: The provider status could not be mapped. - DRAFT: The invoice has not been issued. - ISSUED: The provider issued the invoice and it is awaiting payment. - SENT: Deprecated alias accepted in status filters. Responses use ISSUED. - PARTIALLY_PAID: Some, but not all, of the amount due has been paid. - PAID: The invoice has been paid. - OVERDUE: The invoice is past its due date and remains unpaid. - UNCOLLECTIBLE: The provider no longer expects to collect the invoice. - VOID: The invoice was canceled and is no longer collectible. - CREDITED: The invoice was settled by credit. Type: `enum` ## [License](/end-user-api/models#models/License) A license represents a permission to use a software product with embedded customer and product offering details. Type: `object` - `activatedAt` (`string`, required, date, example 2024-01-15) — The date when the license was activated. - `assignedTo` (`object`, optional) — The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription. - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `cancelledAt` (`string`, optional, date, example 2024-06-30) — The date when the license was canceled (if applicable). - `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. - `details` (`object`, optional) — Additional license details specific to certain license types. - `propertyName` (`any`, optional) — Any additional properties, passed through as given. - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `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) - `pausedAt` (`string`, optional, date, example 2024-03-01) — The date when the license was paused (if applicable). - `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. Present only while a status change is scheduled. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `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. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `type` (`string`, required, example PBX_USER_LEVEL) — The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. ## [LicenseListItem](/end-user-api/models#models/LicenseListItem) Simplified license representation optimized for list operations. The detailed License schema adds the customer and the product offering. Type: `object` - `activatedAt` (`string`, optional, date, example 2024-01-15) — The date when the license was activated. - `cancelledAt` (`string`, optional, date, example 2024-06-30) — The date when the license was canceled. - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering that the license grants. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription that the license is assigned to. Absent for a license that stands alone. - `type` (`string`, required, example PBX_USER_LEVEL) — The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. ## [LicenseStatus](/end-user-api/models#models/LicenseStatus) Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons Type: `enum` ## [LicenseType](/end-user-api/models#models/LicenseType) The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. Type: `string` ## [LineItemSim](/end-user-api/models#models/LineItemSim) The choice between eSIM and physical SIM plus related device details. Type: `object` - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. ## [Metadata](/end-user-api/models#models/Metadata) 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. Type: `object with string keys` - `*` (`string`, optional) ## [NetworkCoverage](/end-user-api/models#models/NetworkCoverage) Network coverage information for a location. Networks answer two different questions. One resolves the address to a point and grades the signal there. Another qualifies a whole postal area for activation and grades nothing. Read `scope` to know which answer you got, and read `serviceable` for the verdict itself. What data is returned depends on the underlying network provider, so only the required fields are guaranteed to be present. Type: `object` - `address` (`object`, required) — The address that was checked. — A location to check network coverage at. Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it. - `city` (`string`, optional, 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). - `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`, optional, 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. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `coordinates` (`object`, optional) — Resolved coordinates for the address, if available. — A geographic location in WGS84 coordinates, the standard used by GPS. - `latitude` (`number`, required, float, personal data, example 40.7128) — Latitude in decimal degrees. Positive values are north of the equator. - `longitude` (`number`, required, float, personal data, example -74.006) — Longitude in decimal degrees. Negative values are west of the prime meridian. - `coverage` (`object with string keys`, optional) — Coverage information per technology, if available. - `3g` (`object`, required) — Coverage details for a single network technology (such as 4G or 5G) at a checked location. - `available` (`boolean`, required, example true) — Whether this technology is available at the checked location. - `4g` (`object`, required) — Coverage details for a single network technology (such as 4G or 5G) at a checked location. - `available` (`boolean`, required, example true) — Whether this technology is available at the checked location. - `5g` (`object`, required) — Coverage details for a single network technology (such as 4G or 5G) at a checked location. - `available` (`boolean`, required, example true) — Whether this technology is available at the checked location. - `*` (`object`, optional) — Coverage details for a single network technology (such as 4G or 5G) at a checked location. - `available` (`boolean`, required, example true) — Whether this technology is available at the checked location. - `coverageLevel` (`enum`, optional, one of EXCELLENT, GOOD, FAIR, POOR, NO_COVERAGE, example GOOD) — Overall network coverage quality at this location. Absent when the network grades no signal. Do not read an absent grade as poor coverage: read `serviceable` instead. - `networkProviderId` (`string`, optional, example tmobile-us) — Which network this coverage data applies to. - `roamingStatus` (`string`, optional, example HOME) — The roaming status at this location, if reported by the network provider (e.g., whether the location is served by the home network or a roaming partner). - `scope` (`enum`, required, one of ADDRESS, POSTAL_AREA, example ADDRESS) — What the verdict applies to. `ADDRESS` means the network placed the exact address and answered about that point. `POSTAL_AREA` means the network read the zip code alone, so the same answer applies to every address in it. - `serviceable` (`boolean`, required, example true) — Whether the network serves this location. Every network answers this. A network that grades signal reports `true` when at least one technology reaches the location. A network that qualifies a postal area reports `true` when it can activate a subscription there. ## [Order](/end-user-api/models#models/Order) A shopping cart for telecommunications services and products. Add line items to configure services, get pricing, and submit for fulfillment. Orders track progress from creation through completion. Type: `object` - `billing` (`object`, optional) — Billing information for an order. For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level. - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no 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. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. - `completedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the order was completed. - `consents` (`object with string keys`, optional, example {"marketing":"true","termsOfService":"true"}) — The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later. - `*` (`string`, optional) - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `createdEntities` (`object`, optional) — Entities created as part of order fulfillment. - `addons` (`array of any`, optional) — Add-ons created during order fulfillment. - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the add-on was canceled (if applicable). - `licenseId` (`string`, optional, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier of the license associated with this add-on (if applicable). - `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) - `productOfferingGroupId` (`string`, optional, example extra-data-packages) — The unique identifier for the product offering group. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. - `referenceId` (`string`, optional, max length 255, example telna-package-12345) — A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider. - `status` (`enum`, required, one of PENDING, ACTIVE, CANCELLED, EXPIRED) — The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. - `createdByLineItem` (`string`, required, example h47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this add-on. - `licenses` (`array of any`, optional) — Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here. - `activatedAt` (`string`, optional, date, example 2024-01-15) — The date when the license was activated. - `cancelledAt` (`string`, optional, date, example 2024-06-30) — The date when the license was canceled. - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering that the license grants. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription that the license is assigned to. Absent for a license that stands alone. - `type` (`string`, required, example PBX_USER_LEVEL) — The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. - `createdByLineItem` (`string`, required, example j47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this license. - `modifications` (`array of any`, optional) — Modifications applied during order fulfillment. - `appliedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the modification was applied. - `newProductOfferingId` (`string`, optional, example po_mobile_premium_plus) — The product offering the entity was changed to. - `targetId` (`string`, required, example e8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription or add-on that was modified. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE, ADDON_CHANGE) — Type of modification applied. - `createdByLineItem` (`string`, required, example i47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this modification. - `subscriptions` (`array of any`, optional) — Subscriptions created during order fulfillment. - `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. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer who owns this subscription. - `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, 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. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering associated with this subscription. - `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 - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier for the subscriber associated with this subscription. - `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. - `createdByLineItem` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this subscription. - `customer` (`object`, optional) — The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment. - `customerId` (`string`, optional, example b47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `name` (`string`, required, example John Doe) — Customer name. - `newCustomer` (`boolean`, required, example true) — Indicates if the customer was/will be created as part of order fulfillment. - `expiresAt` (`string`, required, date-time, example 2024-01-22T10:30:00Z) — When the order expires if not submitted (automatically refreshed on each order update to maintain active session). - `externalPayment` (`object`, optional) — External payment details if the order was paid outside the system. - `receiptDescription` (`string`, optional, example Payment via external billing system) — Description of the external payment. - `receiptUrl` (`string`, optional, uri, example https://external.example.com/receipts/123) — URL to the external payment receipt. - `receivedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the external payment was recorded. - `reference` (`string`, optional, example ext-payment-ref-123) — Reference from the external payment system. - `lineItems` (`array of OrderLineItem`, required) — Line items in the order. - One of: `SUBSCRIPTION` - `activateOnDemand` (`boolean`, optional, example true) — Whether the subscription waits for the subscriber to activate it rather than being activated on a date. The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time. Cannot be combined with scheduleActivationAt. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `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`, optional, personal data, example +15551234567) — The phone number for this subscription. - Leave empty to have one assigned. - When the number pool is available, you can choose a number from the pool and provide the leaseToken. - When porting a number, provide the number and porting details. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `sim` (`object`, optional) — The choice between eSIM and physical SIM plus related device details. This value is optional while the order is a draft. You must give it before you submit the order. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriber` (`object`, optional) — The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at 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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `tempNumber` (`boolean`, optional, example true) — Whether to use a temporary number until the porting is completed. If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized. Can only be used when porting in a number (i.e., when msisdn and porting details are provided). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - One of: `SUBSCRIPTION_CHANGE` - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription. The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `simChange` (`object`, optional) — The SIM card change. Give this value only for changeType SIM_CHANGE. — A change of the SIM card of a subscription. The change carries a one-time price. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `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) - `orderId` (`string`, required, example order-123) — Unique identifier for the order. - `paymentProfileSessionId` (`string`, optional, example 69321a62-f1fe-461f-8761-a19ae6587bb2) — The payment profile session used to set up a payment method for this order, set when the order was submitted with one. - `paymentSessionId` (`string`, optional, example d2e3f4a5-b6c7-8901-2345-012345678901) — The payment session that collected payment for this order, set when the order was submitted with one. - `pricing` (`object`, optional) — Detailed pricing information for an order including taxes and discounts. - `amountDueNowMinor` (`integer`, optional, int64, example 13739) — What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month. This is not `totalMinor`, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `period` (`object`, optional) — Period covered by the initial invoice. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 116) — Estimated tax on initial invoice charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `recurringCosts` (`object`, optional) — Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges. A discount that ends with the periods paid for up front is not applied here. - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Estimated tax on recurring charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — The net of the order after discounts, in minor currency units. When `taxIncluded` is false, add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off the total instead, so the amount before discounts is `totalMinor` plus the discounts. - `taxAmountMinor` (`integer`, optional, int64, example 1008) — Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately. - `taxEstimated` (`boolean`, optional, example false) — Whether the amounts leave out a tax that is not calculated yet. In a region where the tax depends on the address, the tax is calculated when the payment starts, and this field is true until then. When `taxIncluded` is also true, the tax is a part of `totalMinor`. Otherwise the tax is added to it. - `taxIncluded` (`boolean`, optional, example true) — Whether every line was priced with its tax as a part of the price. When true, the discounts came off `totalMinor` and `taxAmountMinor` is the tax inside it. When false, the discounts came off `subtotalMinor` and the tax was added on top. Absent when the order has no priced line yet. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `lineItems` (`array of OrderLineItemPricing`, optional) — Pricing breakdown per line item. - `chargedMonthAmountMinor` (`integer`, optional, int64, example 14458) — What one month this order charges for costs, in minor currency units. Quote this next to `totalMinor` on an order that pays for several months at once, because `recurringAmountMinor` is what a month costs once the order renews, which is more. Do not divide `totalMinor` by `chargedMonths` instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in `totalMinor` but not in these two fields. - `chargedMonths` (`integer`, optional, example 6) — How many consecutive months cost `chargedMonthAmountMinor`. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `discounts` (`array of OrderPricingDiscount`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `recurringDiscounts` (`array of OrderPricingDiscount`, optional) — The individual discounts inside `recurringAmountMinor`, for one billing period. Add back the ones that carry a `validTo` to get what the line costs after they stop. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `subtotalMinor` (`integer`, required, int64, example 2999) — The net of this line item after discounts, in minor currency units. When `taxIncluded` is false, add `totalDiscountsMinor` to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off `totalMinor` instead. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — The individual taxes and regulatory fees making up `taxAmountMinor`, as reported by the tax authority for this line item. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. - `taxIncluded` (`boolean`, optional, example true) — Whether the line was priced with its tax as a part of the price. When true, `totalMinor` is the listed price less the discounts and `taxAmountMinor` is the tax inside it. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, in minor currency units. - `promoCode` (`string`, optional, example STUDENT2024) — Promotional code applied to this order, if any. - `requirements` (`object`, required) — What this platform expects a checkout to collect before the order is submitted, so a client can build the right flow up front. These are declared per platform, not derived from the contents of the order. Submit enforces what the order itself demands rather than what is declared here: an order with an amount left to collect is refused until that amount is paid, and an order that owes nothing submits without any payment reference. - `requiresPayment` (`enum`, optional, one of NOT_REQUIRED, OPTIONAL, REQUIRED) — Whether a checkout on this platform is expected to collect payment before submitting an order. — Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order. - NOT_REQUIRED: The step does not apply; the order can be submitted without it. - OPTIONAL: The step may be completed, but the order can be submitted without it. - REQUIRED: The step must be completed and its session reference provided when submitting the order. - `requiresPaymentProfile` (`enum`, optional, one of NOT_REQUIRED, OPTIONAL, REQUIRED) — Whether a checkout on this platform is expected to save a payment profile for future billing, passing its paymentProfileSessionId when submitting an order. — Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order. - NOT_REQUIRED: The step does not apply; the order can be submitted without it. - OPTIONAL: The step may be completed, but the order can be submitted without it. - REQUIRED: The step must be completed and its session reference provided when submitting the order. - `requiresSigning` (`enum`, optional, one of NOT_REQUIRED, OPTIONAL, REQUIRED) — Whether a checkout on this platform is expected to capture a digital signature, passing its signingSessionId when submitting an order. — Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order. - NOT_REQUIRED: The step does not apply; the order can be submitted without it. - OPTIONAL: The step may be completed, but the order can be submitted without it. - REQUIRED: The step must be completed and its session reference provided when submitting the order. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `signingSessionId` (`string`, optional, example 8f3b1c2d-4e5f-6789-abcd-1234567890ef) — The signing session that captured the customer's signature for this order, set when the order was submitted with one. - `state` (`enum`, required, one of PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED) — The status of an order in its lifecycle. - PENDING: Order is in cart state, can be modified - PENDING_PAYMENT: Order is locked and awaiting payment completion - SUBMITTED: Order has been submitted for processing - PENDING_APPROVAL: Order is pending approval - PROCESSING: Order is being fulfilled - COMPLETED: Order has been successfully fulfilled - CANCELLED: Order was cancelled before completion - EXPIRED: Order expired due to inactivity - FAILED: Order fulfillment failed - `submittedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the order was submitted for fulfillment. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `user` (`object`, optional) — The person who will log in and manage the services in this order. For a new user, userId is absent until the user is actually created, which happens when payment is initiated or, for orders that collect no payment, at submission. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The email the user logs in with. - `name` (`string`, optional, example John Doe) — The user's full name. - `newUser` (`boolean`, required, example true) — Whether this user is created as part of fulfilling the order. - `userId` (`string`, optional, example c47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's identifier, once the user exists. - `validation` (`object`, required) — The result of the checks that a submit makes on the order and its line items. The checks make sure that each necessary field is set, and that the customer can buy each product offering. Payment is not part of these checks. - `errors` (`array of InlineValidationError`, optional) — Order-level validation errors. - `code` (`enum`, optional, deprecated, one of NOT_AN_INITIAL_OFFERING, ADDON_NOT_APPLICABLE, OFFERING_CHANGE_NOT_AVAILABLE, example NOT_AN_INITIAL_OFFERING) — Deprecated. Use `reason`. A code for the problem. An order sets it when the order cannot buy the product offering of a line item: - NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer. - ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on. - OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering. A problem without a code is a field that is missing or not correct. - `message` (`string`, required, example Subscriber name is required.) — Validation error message. - `property` (`string`, optional, example subscriber.name) — Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email"). - `reason` (`string`, optional, example not_an_initial_offering) — Names the problem. `property_required` is a missing value, `property_invalid` is a value with the wrong format, and `property_conflict` is two values that cannot occur together. Other reasons name a business condition, for example `not_an_initial_offering`. Your client must accept a reason that it does not know. - `isValid` (`boolean`, required, example false) — Whether the order is valid and ready for submission. - `lineItemValidation` (`array of object`, optional) — Validation status for each line item. - `errors` (`array of InlineValidationError`, optional) — Validation errors for this line item. - `code` (`enum`, optional, deprecated, one of NOT_AN_INITIAL_OFFERING, ADDON_NOT_APPLICABLE, OFFERING_CHANGE_NOT_AVAILABLE, example NOT_AN_INITIAL_OFFERING) — Deprecated. Use `reason`. A code for the problem. An order sets it when the order cannot buy the product offering of a line item: - NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer. - ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on. - OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering. A problem without a code is a field that is missing or not correct. - `message` (`string`, required, example Subscriber name is required.) — Validation error message. - `property` (`string`, optional, example subscriber.name) — Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email"). - `reason` (`string`, optional, example not_an_initial_offering) — Names the problem. `property_required` is a missing value, `property_invalid` is a value with the wrong format, and `property_conflict` is two values that cannot occur together. Other reasons name a business condition, for example `not_an_initial_offering`. Your client must accept a reason that it does not know. - `isValid` (`boolean`, optional, example false) — Whether this line item is valid. - `lineItemId` (`string`, optional, example line-item-1) — Reference to the line item. - `missingFields` (`array of string`, optional, example ["subscriber.name","sim.iccid"]) — Required fields that are still missing. - `missingFields` (`array of string`, optional, example ["customer","billing.address"]) — Required fields that are still missing. ## [OrderBilling](/end-user-api/models#models/OrderBilling) Billing information for an order. For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level. Type: `object` - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no 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. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. ## [OrderBillingInput](/end-user-api/models#models/OrderBillingInput) Billing information for an order. For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level. Type: `object` - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no 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. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. ## [OrderCustomerReference](/end-user-api/models#models/OrderCustomerReference) Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer. Type: `one of` - One of: `ExistingCustomerById` - `customerId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically. - One of: `AuthenticatedCustomer` - `authenticatedCustomer` (`boolean`, required, example true) — Always true. - One of: `OrderCustomerReference_NewCustomer` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. ## [OrderCustomerReference_NewCustomer](/end-user-api/models#models/OrderCustomerReference-NewCustomer) Details for creating a new customer together with the order. The customer's default payment profile can be set via the save payment profile endpoint once the customer is created. If referenceId is provided and a customer already exists with that referenceId, the existing customer will be used instead of creating a new one. Type: `object` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. ## [OrderCustomerResult](/end-user-api/models#models/OrderCustomerResult) The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment. Type: `object` - `customerId` (`string`, optional, example b47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `name` (`string`, required, example John Doe) — Customer name. - `newCustomer` (`boolean`, required, example true) — Indicates if the customer was/will be created as part of order fulfillment. ## [OrderCustomerType](/end-user-api/models#models/OrderCustomerType) The type of customer this order is for. This scopes the order to the customer type's context, which affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it. For logged in orders, this must match the customer's type. Type: `enum` ## [OrderHandoffClaim](/end-user-api/models#models/OrderHandoffClaim) The order of a handoff token. Type: `object` - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `orderId` (`string`, required, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The order of the token. ## [OrderHandoffToken](/end-user-api/models#models/OrderHandoffToken) A token that gives an open order to a checkout. A person with the token can see, change, and pay for the order. Give the token only to the user that the order is for. Type: `object` - `expiresAt` (`string`, required, date-time, example 2024-01-15T11:00:00Z) — When the token expires, 1 hour after its creation. The order has its own expiry. - `handoffToken` (`string`, required, example oht_f47ac10b58cc4372a5670e02b2c3d479) — The handoff token. We return it only in this response. If you lose it, create a new token. - `orderId` (`string`, required, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The order of the token. ## [OrderLineItem](/end-user-api/models#models/OrderLineItem) A line item in an order representing a billable action or service. Type: `one of` - One of: `SUBSCRIPTION` - `activateOnDemand` (`boolean`, optional, example true) — Whether the subscription waits for the subscriber to activate it rather than being activated on a date. The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time. Cannot be combined with scheduleActivationAt. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `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`, optional, personal data, example +15551234567) — The phone number for this subscription. - Leave empty to have one assigned. - When the number pool is available, you can choose a number from the pool and provide the leaseToken. - When porting a number, provide the number and porting details. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `sim` (`object`, optional) — The choice between eSIM and physical SIM plus related device details. This value is optional while the order is a draft. You must give it before you submit the order. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriber` (`object`, optional) — The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at 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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `tempNumber` (`boolean`, optional, example true) — Whether to use a temporary number until the porting is completed. If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized. Can only be used when porting in a number (i.e., when msisdn and porting details are provided). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - One of: `SUBSCRIPTION_CHANGE` - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription. The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `simChange` (`object`, optional) — The SIM card change. Give this value only for changeType SIM_CHANGE. — A change of the SIM card of a subscription. The change carries a one-time price. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. ## [OrderLineItemPricing](/end-user-api/models#models/OrderLineItemPricing) The calculated price of a single order line item, with its tax, fee, and discount breakdown. Returned by the order price calculation endpoint so you can show a per-item breakdown before the order is submitted. All amounts are in minor units of the order currency (e.g., 2999 = $29.99 when the currency is USD). Type: `object` - `chargedMonthAmountMinor` (`integer`, optional, int64, example 14458) — What one month this order charges for costs, in minor currency units. Quote this next to `totalMinor` on an order that pays for several months at once, because `recurringAmountMinor` is what a month costs once the order renews, which is more. Do not divide `totalMinor` by `chargedMonths` instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in `totalMinor` but not in these two fields. - `chargedMonths` (`integer`, optional, example 6) — How many consecutive months cost `chargedMonthAmountMinor`. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `discounts` (`array of OrderPricingDiscount`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `recurringDiscounts` (`array of OrderPricingDiscount`, optional) — The individual discounts inside `recurringAmountMinor`, for one billing period. Add back the ones that carry a `validTo` to get what the line costs after they stop. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `subtotalMinor` (`integer`, required, int64, example 2999) — The net of this line item after discounts, in minor currency units. When `taxIncluded` is false, add `totalDiscountsMinor` to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off `totalMinor` instead. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — The individual taxes and regulatory fees making up `taxAmountMinor`, as reported by the tax authority for this line item. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. - `taxIncluded` (`boolean`, optional, example true) — Whether the line was priced with its tax as a part of the price. When true, `totalMinor` is the listed price less the discounts and `taxAmountMinor` is the tax inside it. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, in minor currency units. ## [OrderLineItemStatus](/end-user-api/models#models/OrderLineItemStatus) The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. Type: `enum` ## [OrderListItem](/end-user-api/models#models/OrderListItem) Optimized order representation for list operations. Type: `object` - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `customer` (`object`, optional) — 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. - `expiresAt` (`string`, optional, date-time, example 2024-01-22T10:30:00Z) — When the order will expire if not submitted. - `orderId` (`string`, required, example ce0539b4-ec57-4709-b72e-47892586d05a) — The unique identifier for the order. - `pricing` (`object`, optional) — Summary pricing information for the order. - `currency` (`string`, required, example USD) — ISO 4217 currency code. - `totalMinor` (`integer`, required, int64, example 13739) — Final order total including all taxes and fees, in minor currency units. - `state` (`enum`, required, one of PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED) — The status of an order in its lifecycle. - PENDING: Order is in cart state, can be modified - PENDING_PAYMENT: Order is locked and awaiting payment completion - SUBMITTED: Order has been submitted for processing - PENDING_APPROVAL: Order is pending approval - PROCESSING: Order is being fulfilled - COMPLETED: Order has been successfully fulfilled - CANCELLED: Order was cancelled before completion - EXPIRED: Order expired due to inactivity - FAILED: Order fulfillment failed - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `validationStatus` (`enum`, optional, one of VALID, INVALID, PENDING_VALIDATION) — Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid. ## [OrderModification](/end-user-api/models#models/OrderModification) A modification applied to an existing service during order fulfillment. Type: `object` - `appliedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the modification was applied. - `newProductOfferingId` (`string`, optional, example po_mobile_premium_plus) — The product offering the entity was changed to. - `targetId` (`string`, required, example e8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription or add-on that was modified. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE, ADDON_CHANGE) — Type of modification applied. ## [OrderPricing](/end-user-api/models#models/OrderPricing) Detailed pricing information for an order including taxes and discounts. Type: `object` - `amountDueNowMinor` (`integer`, optional, int64, example 13739) — What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month. This is not `totalMinor`, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `period` (`object`, optional) — Period covered by the initial invoice. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 116) — Estimated tax on initial invoice charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `recurringCosts` (`object`, optional) — Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges. A discount that ends with the periods paid for up front is not applied here. - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Estimated tax on recurring charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — The net of the order after discounts, in minor currency units. When `taxIncluded` is false, add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off the total instead, so the amount before discounts is `totalMinor` plus the discounts. - `taxAmountMinor` (`integer`, optional, int64, example 1008) — Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately. - `taxEstimated` (`boolean`, optional, example false) — Whether the amounts leave out a tax that is not calculated yet. In a region where the tax depends on the address, the tax is calculated when the payment starts, and this field is true until then. When `taxIncluded` is also true, the tax is a part of `totalMinor`. Otherwise the tax is added to it. - `taxIncluded` (`boolean`, optional, example true) — Whether every line was priced with its tax as a part of the price. When true, the discounts came off `totalMinor` and `taxAmountMinor` is the tax inside it. When false, the discounts came off `subtotalMinor` and the tax was added on top. Absent when the order has no priced line yet. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `lineItems` (`array of OrderLineItemPricing`, optional) — Pricing breakdown per line item. - `chargedMonthAmountMinor` (`integer`, optional, int64, example 14458) — What one month this order charges for costs, in minor currency units. Quote this next to `totalMinor` on an order that pays for several months at once, because `recurringAmountMinor` is what a month costs once the order renews, which is more. Do not divide `totalMinor` by `chargedMonths` instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in `totalMinor` but not in these two fields. - `chargedMonths` (`integer`, optional, example 6) — How many consecutive months cost `chargedMonthAmountMinor`. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `discounts` (`array of OrderPricingDiscount`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `recurringDiscounts` (`array of OrderPricingDiscount`, optional) — The individual discounts inside `recurringAmountMinor`, for one billing period. Add back the ones that carry a `validTo` to get what the line costs after they stop. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. - `subtotalMinor` (`integer`, required, int64, example 2999) — The net of this line item after discounts, in minor currency units. When `taxIncluded` is false, add `totalDiscountsMinor` to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off `totalMinor` instead. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — The individual taxes and regulatory fees making up `taxAmountMinor`, as reported by the tax authority for this line item. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. - `taxIncluded` (`boolean`, optional, example true) — Whether the line was priced with its tax as a part of the price. When true, `totalMinor` is the listed price less the discounts and `taxAmountMinor` is the tax inside it. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, in minor currency units. ## [OrderPricingDiscount](/end-user-api/models#models/OrderPricingDiscount) One reduction applied to a line item, with where it came from and how long it lasts. Use `source` to tell a reduction the customer earned from one that every price carries, and `validTo` to tell the customer when the price goes back up. Type: `object` - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `name` (`string`, required, example First month free) — Discount name or description. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, PRICE_LIST, PRICE_LIST_DISCOUNT, BINDING_PERIOD, UPFRONT_PAYMENT, TAG, PROMOTION_CODE, example PROMOTION_CODE) — What gave the customer the discount: - `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms. - `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on. - `BINDING_PERIOD` comes from the contract the customer signed. - `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once. - `TAG` is a campaign the customer carries. - `PROMOTION_CODE` is the promotional code on the order. Omitted on an order priced before this field existed. - `validFrom` (`string`, optional, date) — The first day the discount comes off the price. - `validTo` (`string`, optional, date) — The last day the discount comes off the price. Omitted when the discount never stops. ## [OrderPricingSummary](/end-user-api/models#models/OrderPricingSummary) The price of an order, recalculated whenever the order changes. In regions with complex tax rules (e.g., the US), tax is resolved per jurisdiction from the order's addresses. In other regions, tax depends on customer type but is typically included. All amounts are in minor units of the currency (e.g., 13739 = $137.39 when the currency is USD). Type: `object` - `amountDueNowMinor` (`integer`, optional, int64, example 13739) — What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month. This is not `totalMinor`, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `period` (`object`, optional) — Period covered by the initial invoice. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 116) — Estimated tax on initial invoice charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `recurringCosts` (`object`, optional) — Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges. A discount that ends with the periods paid for up front is not applied here. - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Estimated tax on recurring charges, in minor currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `taxIncluded` (`boolean`, optional, example true) — Whether every line in this total was priced with its tax as a part of the price. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — The net of the order after discounts, in minor currency units. When `taxIncluded` is false, add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. When `taxIncluded` is true, the discounts came off the total instead, so the amount before discounts is `totalMinor` plus the discounts. - `taxAmountMinor` (`integer`, optional, int64, example 1008) — Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately. - `taxEstimated` (`boolean`, optional, example false) — Whether the amounts leave out a tax that is not calculated yet. In a region where the tax depends on the address, the tax is calculated when the payment starts, and this field is true until then. When `taxIncluded` is also true, the tax is a part of `totalMinor`. Otherwise the tax is added to it. - `taxIncluded` (`boolean`, optional, example true) — Whether every line was priced with its tax as a part of the price. When true, the discounts came off `totalMinor` and `taxAmountMinor` is the tax inside it. When false, the discounts came off `subtotalMinor` and the tax was added on top. Absent when the order has no priced line yet. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. ## [OrderRequirement](/end-user-api/models#models/OrderRequirement) Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order. - NOT_REQUIRED: The step does not apply; the order can be submitted without it. - OPTIONAL: The step may be completed, but the order can be submitted without it. - REQUIRED: The step must be completed and its session reference provided when submitting the order. Type: `enum` ## [OrderState](/end-user-api/models#models/OrderState) The status of an order in its lifecycle. - PENDING: Order is in cart state, can be modified - PENDING_PAYMENT: Order is locked and awaiting payment completion - SUBMITTED: Order has been submitted for processing - PENDING_APPROVAL: Order is pending approval - PROCESSING: Order is being fulfilled - COMPLETED: Order has been successfully fulfilled - CANCELLED: Order was cancelled before completion - EXPIRED: Order expired due to inactivity - FAILED: Order fulfillment failed Type: `enum` ## [OrderUserReference](/end-user-api/models#models/OrderUserReference) The person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order. Type: `one of` - One of: `ExistingUserById` - `userId` (`string`, required, example d47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's internal ID. - One of: `AuthenticatedUser` - `authenticatedUser` (`boolean`, required, example true) — Always true. - One of: `OrderUserReference_NewUser` - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `address` (`object`, optional, deprecated) — Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in `customer` instead. — 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. - `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`, optional, phone, personal data, example +15551234567) — The user's phone number. - `name` (`string`, required, example John Doe) — The user's full name. ## [OrderUserReference_NewUser](/end-user-api/models#models/OrderUserReference-NewUser) Details for creating a new user together with the order. The user is created when payment is initiated, or at submission for orders that collect no payment, and can then log in to manage the services they ordered. Type: `object` - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `address` (`object`, optional, deprecated) — Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in `customer` instead. — 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. - `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`, optional, phone, personal data, example +15551234567) — The user's phone number. - `name` (`string`, required, example John Doe) — The user's full name. ## [OrderUserResult](/end-user-api/models#models/OrderUserResult) The person who will log in and manage the services in this order. For a new user, userId is absent until the user is actually created, which happens when payment is initiated or, for orders that collect no payment, at submission. Type: `object` - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The email the user logs in with. - `name` (`string`, optional, example John Doe) — The user's full name. - `newUser` (`boolean`, required, example true) — Whether this user is created as part of fulfilling the order. - `userId` (`string`, optional, example c47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's identifier, once the user exists. ## [Pagination](/end-user-api/models#models/Pagination) Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. Type: `object` - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ## [PauseSubscriptionRequest](/end-user-api/models#models/PauseSubscriptionRequest) Request to pause a subscription. The customer stops paying and service is disabled. 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. ## [PaymentAttempt](/end-user-api/models#models/PaymentAttempt) A single charge attempt against a payment intent. Type: `object` - `amountMinor` (`integer`, required, int64, example 2900) — The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `chargedAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the charge was made. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the attempt was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. ## [PaymentIntent](/end-user-api/models#models/PaymentIntent) The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items. A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice. Type: `object` - `amountMinor` (`integer`, required, int64, example 2900) — The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `attempts` (`array of PaymentAttempt`, required) — Charge attempts made against this payment intent, most recent first. - `amountMinor` (`integer`, required, int64, example 2900) — The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `chargedAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the charge was made. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the attempt was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `description` (`string`, optional, example Mobile subscription renewal) — A human-readable description of what is being collected. - `discounts` (`array of PaymentIntentDiscount`, required) — Reductions applied to the payment intent as a whole rather than to one billed line. - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. - `dueAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the amount is due. - `lineItems` (`array of PaymentIntentLineItem`, required) — The items that make up the collected amount. - `amountMinor` (`integer`, required, int64, example 2900) — The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless `includesTax` is true and they are a part of it. - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `refunds` (`array of PaymentRefund`, required) — Refunds issued against this payment intent. - `amountMinor` (`integer`, required, int64, example 2900) — The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the refund is issued in (e.g., "USD"). - `reason` (`enum`, optional, one of UNKNOWN, DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, DISPUTE_LOST, example REQUESTED_BY_CUSTOMER) — Why the refund was issued. - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. - `status` (`enum`, required, one of UNKNOWN, PENDING, REQUIRES_ACTION, PROCESSING, SUCCEEDED, REQUIRES_PAYMENT_METHOD, CANCELED, example SUCCEEDED) — Current stage of a payment intent as it is collected through the payment provider. - UNKNOWN: The platform has no supported mapping for the current provider state. - PENDING: Created, no charge attempted yet. - REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication). - PROCESSING: A charge is in flight with the payment provider. - SUCCEEDED: The full amount has been collected. - REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry. - CANCELED: Collection was canceled and no further charges will be attempted. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. ## [PaymentIntentDiscount](/end-user-api/models#models/PaymentIntentDiscount) A reduction applied to the payment intent as a whole rather than to one billed line. Type: `object` - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. ## [PaymentIntentLineItem](/end-user-api/models#models/PaymentIntentLineItem) A single billed item contributing to a payment intent's amount. Type: `object` - `amountMinor` (`integer`, required, int64, example 2900) — The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless `includesTax` is true and they are a part of it. - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). ## [PaymentIntentListItem](/end-user-api/models#models/PaymentIntentListItem) A payment intent without its nested attempts, refunds, and line items, optimized for list views. Type: `object` - `amountMinor` (`integer`, required, int64, example 2900) — The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `description` (`string`, optional, example Mobile subscription renewal) — A human-readable description of what is being collected. - `dueAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the amount is due. - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `status` (`enum`, required, one of UNKNOWN, PENDING, REQUIRES_ACTION, PROCESSING, SUCCEEDED, REQUIRES_PAYMENT_METHOD, CANCELED, example SUCCEEDED) — Current stage of a payment intent as it is collected through the payment provider. - UNKNOWN: The platform has no supported mapping for the current provider state. - PENDING: Created, no charge attempted yet. - REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication). - PROCESSING: A charge is in flight with the payment provider. - SUCCEEDED: The full amount has been collected. - REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry. - CANCELED: Collection was canceled and no further charges will be attempted. - `type` (`enum`, required, one of UNKNOWN, PREPAID_RENEWAL, TOPUP, INITIAL_ORDER, example PREPAID_RENEWAL) — What the payment intent collects. - UNKNOWN: The platform does not have a supported type for this intent. - PREPAID_RENEWAL: A scheduled prepaid subscription renewal. - TOPUP: An immediate prepaid balance or allowance top-up. - INITIAL_ORDER: Payment collected while placing an order. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. ## [PaymentIntentStatus](/end-user-api/models#models/PaymentIntentStatus) Current stage of a payment intent as it is collected through the payment provider. - UNKNOWN: The platform has no supported mapping for the current provider state. - PENDING: Created, no charge attempted yet. - REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication). - PROCESSING: A charge is in flight with the payment provider. - SUCCEEDED: The full amount has been collected. - REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry. - CANCELED: Collection was canceled and no further charges will be attempted. Type: `enum` ## [PaymentIntentType](/end-user-api/models#models/PaymentIntentType) What the payment intent collects. - UNKNOWN: The platform does not have a supported type for this intent. - PREPAID_RENEWAL: A scheduled prepaid subscription renewal. - TOPUP: An immediate prepaid balance or allowance top-up. - INITIAL_ORDER: Payment collected while placing an order. Type: `enum` ## [PaymentProvider](/end-user-api/models#models/PaymentProvider) Payment service provider that processes the transaction. Type: `enum` ## [PaymentRefund](/end-user-api/models#models/PaymentRefund) A refund issued against a payment intent. Type: `object` - `amountMinor` (`integer`, required, int64, example 2900) — The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD). - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the refund is issued in (e.g., "USD"). - `reason` (`enum`, optional, one of UNKNOWN, DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, DISPUTE_LOST, example REQUESTED_BY_CUSTOMER) — Why the refund was issued. - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. ## [PaymentSession](/end-user-api/models#models/PaymentSession) A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow, let the customer pay, then pass its paymentSessionId when you submit the order. There are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the customer to that page. An embedded session (create it with hosted set to false) gives you providerContext, and you show the payment form inside your own checkout page. Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds. Type: `object` - `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel the payment. - `createdAt` (`string`, required, date-time, example 2024-09-29T10:00:00Z) — When this payment session was created. - `hostedUrl` (`string`, optional, uri, example https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901) — The hosted checkout page to redirect the customer to in order to complete payment. A hosted session only. - `metadata` (`object with string keys`, required, example {"campaign":"summer_2024","source":"mobile_app"}) — Custom key-value pairs for additional payment session information. - `*` (`string`, optional) - `orderId` (`string`, required, example e3f4a5b6-c7d8-9012-3456-123456789012) — The unique identifier of the order this payment session is for. - `paymentProfileId` (`string`, optional, example f4a5b6c7-d8e9-0123-4567-234567890123) — The saved payment method to use for this payment (for returning customers). - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `paymentSessionId` (`string`, required, example d2e3f4a5-b6c7-8901-2345-012345678901) — The unique identifier for this payment session. - `providerContext` (`object`, optional) — What the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead. This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `stripe` (`object`, optional) — The Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser. - `clientSecret` (`string`, required, example cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5) — The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. - `returnUrl` (`string`, optional, example https://example.com/order/confirmation) — The URL the customer is redirected to after payment completion. - `savePaymentProfile` (`boolean`, required, example true) — Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false. - `status` (`enum`, required, one of PENDING, REQUIRES_ACTION, COMPLETED, FAILED, CANCELED, EXPIRED, example PENDING) — Current status of a payment session lifecycle. - `updatedAt` (`string`, required, date-time, example 2024-09-29T10:30:00Z) — When this payment session was last updated. ## [PaymentSessionBranding](/end-user-api/models#models/PaymentSessionBranding) The colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form. Type: `object` - `backgroundColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #ffffff) — The background color of the payment form, as a hex value with a leading number sign. - `borderStyle` (`enum`, optional, one of PILL, RECTANGULAR, ROUNDED, example PILL) — The shape of the buttons and the input fields of the payment form. - `buttonColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #0cf68c) — The color of the payment button, as a hex value with a leading number sign. - `displayName` (`string`, optional, max length 100, example Seamless) — The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms. ## [PaymentSessionProviderContext](/end-user-api/models#models/PaymentSessionProviderContext) What the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead. This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider. Type: `object` - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `stripe` (`object`, optional) — The Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser. - `clientSecret` (`string`, required, example cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5) — The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. ## [PaymentSessionStatus](/end-user-api/models#models/PaymentSessionStatus) Current status of a payment session lifecycle. Type: `enum` ## [PortingDetails](/end-user-api/models#models/PortingDetails) 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. Type: `one of` - 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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. ## [PortingDetailsSweden](/end-user-api/models#models/PortingDetailsSweden) Information required to port a Swedish phone number. Swedish carriers approve a transfer based on the national identity number of the number's current owner, so no account number or PIN is needed. Type: `object` - `identity` (`string`, required, personal data, 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. ## [PortingDetailsUS](/end-user-api/models#models/PortingDetailsUS) Information required to port a US phone number. Provide firstName, lastName, and address in the initial request; accountNumber and passcode (often called a Number Transfer PIN) may be omitted at first but must be supplied before the port can be activated. US carriers validate a transfer against the losing carrier's account records, and mismatches are the most common cause of rejected ports, so these values must match the losing carrier's records exactly. Type: `object` - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. ## [PortingDirection](/end-user-api/models#models/PortingDirection) 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. Type: `enum` ## [PortingEligibilityResult](/end-user-api/models#models/PortingEligibilityResult) Result of number porting eligibility check. Type: `object` - `eligible` (`boolean`, required, example true) — Whether the number is eligible for porting. - `ineligibilityReason` (`string`, optional, example Number not found or not portable) — Reason why number is not eligible (only present if eligible is false). - `msisdn` (`string`, required, phone, personal data, example +15551234567) — The phone number that was checked. - `networkProviderId` (`string`, optional, example tmobile-us) — The identifier for the current network provider, if detectable ## [PortingStatus](/end-user-api/models#models/PortingStatus) 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 Type: `enum` ## [Price](/end-user-api/models#models/Price) 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. Type: `object` - `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. ## [PriceDiscount](/end-user-api/models#models/PriceDiscount) 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. Type: `object` - `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. ## [PriceType](/end-user-api/models#models/PriceType) 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). Type: `enum` ## [ProductCatalogSection](/end-user-api/models#models/ProductCatalogSection) A heading in a product catalog, and the product offerings under it in the order that a checkout shows them. Type: `object` - `description` (`string`, optional, example Plans with unlimited calls and texts) — The text under the heading. Absent when the section has none. - `name` (`string`, required, example Mobile plans) — The heading of the section. - `productCatalogSectionId` (`string`, required, example 0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90) — Unique identifier for the section. - `productOfferingIds` (`array of string`, required) — The product offerings in the section, in display order. ## [ProductCategory](/end-user-api/models#models/ProductCategory) 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. Type: `enum` ## [ProductOffering](/end-user-api/models#models/ProductOffering) A product offering is a product combined with a price that is offered to customers. The offering's `type` and `category` are available via the nested `product` object. See ProductType and ProductCategory schemas for available values and their meanings. Type: `object` - `addonCategories` (`array of ProductCategory`, optional) — List of product categories this addon is applicable for. Only populated when type is `SUBSCRIPTION_ADDON`. For example, a `TRAVEL_ESIM_PACKAGE` addon might be applicable to `TRAVEL_ESIM` subscriptions. - `broadbandFacts` (`object`, optional) — The values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price. - `additionalDataIncrementGb` (`number`, required, example 0) — The amount of data, in GB, that `overUsageDataPriceMinor` buys. Always 0, because the platform sells no data after the allowance. - `earlyTerminationFeeMinor` (`integer`, required, int64, example 0) — The fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee. - `monthlyProviderFees` (`array of BroadbandFactsFee`, required) — The fees that the provider adds to the monthly price. - `amountMinor` (`integer`, required, int64, example 21) — The amount of the fee, in minor currency units. - `name` (`string`, required, example Federal Universal Service Fund) — What the label calls the fee. - `overUsageDataPriceMinor` (`integer`, required, int64, example 0) — The price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price. - `planCode` (`string`, required, example FLEXSTANDARD001) — 15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan identifier on the label is `M`, then the FCC Registration Number of the brand, then this code. - `singlePurchaseFees` (`array of BroadbandFactsFee`, required) — The fees that the customer pays one time, when they buy the plan. - `amountMinor` (`integer`, required, int64, example 21) — The amount of the fee, in minor currency units. - `name` (`string`, required, example Federal Universal Service Fund) — What the label calls the fee. - `unlimitedData` (`boolean`, required, example false) — True when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `description` (`string`, optional, example Basic mobile plan with 5GB data and unlimited calls) — Description of the product offering. - `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. - `internalDescription` (`string`, optional, example seamless_cell_10gb_us) — Internal description of the product offering for operational use only. - `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) - `name` (`string`, required, example Seamless 10GB) — Name of the product offering. - `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. - `product` (`object`, required) — Embedded representation of a product. - `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. - `features` (`object`, optional) — The features included with the product, if any. Typically used for telecom products. - `activationType` (`enum`, optional, one of INSTANT, FIRST_USE, example INSTANT) — How the travel eSIM package activates. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `countries` (`array of string`, optional, example ["USA","CAN","MEX"]) — ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `countries` query parameter on list endpoints to filter by coverage. - `dataMb` (`number`, optional, example 2048) — Megabytes of data included with the product. Present for cellular, data, and travel eSIM products. - `includedCallSeconds` (`integer`, optional, example 1000) — Outbound call seconds included with the product. Present for cellular subscription categories. - `includedSms` (`integer`, optional, example 500) — Number of SMS messages included with the product. Present for cellular subscription categories. - `regions` (`array of string`, optional, example ["NORTH_AMERICA"]) — Named regions covered by the product. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `regions` query parameter on list endpoints to filter by coverage. - `simCardType` (`enum`, optional, one of PSIM, ESIM, example PSIM) — The SIM format for a SIM card product. - `validityDays` (`integer`, optional, example 30) — Number of days the product is valid for. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `internalName` (`string`, required, example us-mobile-unlimited-5gb) — The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead. - `networkProviderId` (`string`, optional, example tmobile-us) — The unique identifier for the network provider. - `productId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-890123456789) — The unique identifier for the product. - `type` (`enum`, required, one of SUBSCRIPTION, SUBSCRIPTION_ADDON, LICENSE, EXTERNAL_PRODUCT, SIM_CARD, example SUBSCRIPTION) — The type of product offering determines how it can be used and what kind of resource it creates. **SUBSCRIPTION** Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM). - Includes categories like `SUBSCRIPTION_CELL`, `TRAVEL_ESIM` - Can be created via order or directly depending on configuration - Has its own lifecycle (activation, suspension, termination) **SUBSCRIPTION_ADDON** Adds features or resources to an existing subscription. - Includes categories like `TRAVEL_ESIM_PACKAGE` - Must be attached to a parent subscription **LICENSE** Creates a license for business/PBX features. - Typically used for enterprise telephony features **EXTERNAL_PRODUCT** Represents purchasable items outside the core telecom platform. - Can only be ordered via orders, not created directly **SIM_CARD** Replaces the SIM card for an existing subscription through a subscription change order. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the product offering. - `richContent` (`string`, optional, example

Features

  • 5GB monthly data
  • Unlimited calls & texts
  • No setup fees
) — Rich HTML content with detailed information about the product offering. - `status` (`enum`, required, deprecated, one of AVAILABLE, ARCHIVED, example AVAILABLE) — Deprecated. Use `versionStatus` instead. The status of the product offering. Archived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions. - `uspList` (`array of string`, optional, example ["5GB of data every month","Unlimited calls and texts","No setup fee"]) — Short plain-text selling points, in the order the brand put them. A storefront shows them as a checklist. - `versionStatus` (`enum`, required, one of DRAFT, TESTING, PUBLISHED, UNPUBLISHED, ARCHIVED, example PUBLISHED) — The stage of this version of the product offering. - `DRAFT`: The brand edits the version. Nobody can order it. - `TESTING`: The brand tests the version. Nobody can order it. - `PUBLISHED`: Each customer can order the version. - `UNPUBLISHED`: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it. - `ARCHIVED`: Nobody can order the version. Existing subscriptions keep it. ## [ProductOfferingChangeSchedule](/end-user-api/models#models/ProductOfferingChangeSchedule) 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 Type: `enum` ## [ProductOfferingGroup](/end-user-api/models#models/ProductOfferingGroup) A product group organizes related product offerings. Type: `object` - `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. ## [ProductOfferingOption](/end-user-api/models#models/ProductOfferingOption) A product offering option available for subscription changes with scheduling information. Type: `object` - `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. ## [ProductOfferingVersionStatus](/end-user-api/models#models/ProductOfferingVersionStatus) The stage of this version of the product offering. - `DRAFT`: The brand edits the version. Nobody can order it. - `TESTING`: The brand tests the version. Nobody can order it. - `PUBLISHED`: Each customer can order the version. - `UNPUBLISHED`: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it. - `ARCHIVED`: Nobody can order the version. Existing subscriptions keep it. Type: `enum` ## [ProductType](/end-user-api/models#models/ProductType) The type of product offering determines how it can be used and what kind of resource it creates. **SUBSCRIPTION** Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM). - Includes categories like `SUBSCRIPTION_CELL`, `TRAVEL_ESIM` - Can be created via order or directly depending on configuration - Has its own lifecycle (activation, suspension, termination) **SUBSCRIPTION_ADDON** Adds features or resources to an existing subscription. - Includes categories like `TRAVEL_ESIM_PACKAGE` - Must be attached to a parent subscription **LICENSE** Creates a license for business/PBX features. - Typically used for enterprise telephony features **EXTERNAL_PRODUCT** Represents purchasable items outside the core telecom platform. - Can only be ordered via orders, not created directly **SIM_CARD** Replaces the SIM card for an existing subscription through a subscription change order. Type: `enum` ## [ResetNetworkServicesRequest](/end-user-api/models#models/ResetNetworkServicesRequest) Confirms that the user approved a temporary interruption while network services are reset. Type: `object` - `confirmed` (`boolean`, required, example true) — Must be true after the user explicitly approves the temporary service interruption. ## [ResetNetworkServicesResult](/end-user-api/models#models/ResetNetworkServicesResult) Current state of a subscription network-services reset. Type: `object` - `createdAt` (`string`, optional, date-time) — When the reset workflow action was created. - `finishedAt` (`string`, optional, date-time) — When execution finished, if it has finished. - `networkProvider` (`string`, required) — Network provider selected for this subscription. - `observedAt` (`string`, required, date-time) — When this status was read. - `outcome` (`enum`, required, one of STARTED, ALREADY_RUNNING, RECENT_SUCCESS, RECENT_FAILURE, OPERATOR_UNSUPPORTED) — Whether a reset was started or an existing recent reset was returned. - `startedAt` (`string`, optional, date-time) — When execution started, if it has started. - `status` (`enum`, required, one of PENDING, RUNNING, SUCCEEDED, FAILED, UNSUPPORTED) — Current workflow state. - `subscriptionActionId` (`string`, optional) — Identifier of the reset workflow action. Absent when the network provider is unsupported. - `subscriptionId` (`string`, required) — Subscription whose network services are being reset. ## [RestoreSubscriptionRequest](/end-user-api/models#models/RestoreSubscriptionRequest) Request to restore a suspended, paused, or blocked subscription back to active state. 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. ## [RoamingCostControl](/end-user-api/models#models/RoamingCostControl) The roaming cost-control setting for one subscription. This cost limit is separate from roaming data allowances and top-up balances. Type: `object` - `currency` (`string`, optional, example USD) — The currency of limitMinor. It is present only when state is ACTIVE. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `limitMinor` (`integer`, optional, int64, >= 0, example 52000) — The configured cost limit in minor currency units. It is present only when state is ACTIVE. - `observedAt` (`string`, required, date-time) — The time when the platform read this setting. - `provider` (`string`, required, example telia) — The network provider that supplies the setting. - `state` (`enum`, required, one of ACTIVE, NOT_CONFIGURED, UNSUPPORTED, UNAVAILABLE) — The availability and configuration state of roaming cost control. - `subscriptionId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription that owns this roaming cost-control setting. ## [SearchDevicesRequest](/end-user-api/models#models/SearchDevicesRequest) Request to find devices by name. Use this when the customer knows their device by its everyday name and not by its IMEI, for example to find out whether it supports eSIM before they order. Type: `object` - `limit` (`integer`, optional, >= 1, <= 50, default 20, example 20) — The largest number of devices to return. - `query` (`string`, required, min length 2, example iPhone 15) — Part of the device name to match, such as the brand, the model, or both. ## [Shipping](/end-user-api/models#models/Shipping) Shipping information for order fulfillment. Only required if the order contains shippable items. Type: `object` - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. ## [ShippingInput](/end-user-api/models#models/ShippingInput) Shipping information for order fulfillment. Only required if the order contains shippable items. Type: `object` - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. ## [SimType](/end-user-api/models#models/SimType) The technology type of the SIM card. - PHYSICAL: A plastic SIM card that is shipped and inserted into the device - ESIM: An embedded SIM profile that is downloaded digitally to the device, typically via QR code Type: `enum` ## [StartEmailLoginRequest](/end-user-api/models#models/StartEmailLoginRequest) Request to initiate an email-based login flow. A verification code will be sent to the provided email address. Type: `object` - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email address to send the verification code to. ## [StartEmailLoginResponse](/end-user-api/models#models/StartEmailLoginResponse) Response from initiating an email login. Contains the nonce needed for verification and timing information. Type: `object` - `createdAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the authentication request was created. - `expiresAt` (`string`, required, date-time, example 2024-01-15T10:35:00Z) — When the verification code will expire. - `expiresIn` (`integer`, required, example 300) — Number of seconds until the verification code expires. - `nonce` (`string`, required, example a1b2c3d4-e5f6-7890-abcd-ef1234567890) — Token to reference this authentication request during verification. ## [Storefront](/end-user-api/models#models/Storefront) The product catalogs that a storefront sells from, and the sections that it shows their product offerings in. Type: `object` - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — The kind of customer that these catalogs sell to. — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `initialProductOfferingIds` (`array of string`, optional) — The initial product offerings of these catalogs. A customer can order them as a new subscription or as an external product. A storefront with no sections shows these product offerings. - `productCatalogIds` (`array of string`, required) — The product catalogs that the storefront sells from. Empty when no catalog applies. - `sections` (`array of ProductCatalogSection`, required) — The sections of these catalogs, in display order. A section gives only initial product offerings. - `description` (`string`, optional, example Plans with unlimited calls and texts) — The text under the heading. Absent when the section has none. - `name` (`string`, required, example Mobile plans) — The heading of the section. - `productCatalogSectionId` (`string`, required, example 0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90) — Unique identifier for the section. - `productOfferingIds` (`array of string`, required) — The product offerings in the section, in display order. - `simTypes` (`array of SimType`, optional) — The SIM types that the storefront sells with a new subscription. A subscription line with another SIM type cannot go through the checkout of the storefront. Empty when the storefront sells no SIM type. ## [StripeCheckoutContext](/end-user-api/models#models/StripeCheckoutContext) The Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser. Type: `object` - `clientSecret` (`string`, required, example cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5) — The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. ## [SubmitOrderRequest](/end-user-api/models#models/SubmitOrderRequest) Request to submit an order for fulfillment. Depending on the order's requirements, payment intent, saved payment profile, or signing reference may be required. In a fully managed flow, the order may be auto-submitted on successfully fulfilling all requirements (e.g. successful payment or signing). Type: `object` - `externalPayment` (`object`, optional) — Details of an external payment made outside the system. When provided, the order is considered paid and will bypass internal payment requirements. Cannot be used together with paymentSessionId. - `receiptDescription` (`string`, optional, example Payment via external billing system) — Optional human-readable description of the payment. - `receiptUrl` (`string`, optional, uri, example https://external.example.com/receipts/123) — Optional URL to a receipt or confirmation page for the payment. - `reference` (`string`, required, min length 1, example ext-payment-ref-123) — Reference or identifier from the external payment system. - `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) - `paymentProfileSessionId` (`string`, optional, example b2c3d4e5-f6a7-8901-2345-6789abcdef01) — Reference to completed payment profile session for zero-total orders requiring payment method setup. - `paymentSessionId` (`string`, optional, example a1b2c3d4-e5f6-7890-1234-56789abcdef0) — Reference to completed payment session for orders requiring payment collection. - `signingSessionId` (`string`, optional, example c3d4e5f6-a7b8-9012-3456-789abcdef012) — Reference to completed signing session. ## [Subscriber](/end-user-api/models#models/Subscriber) The person or entity that uses a subscription's service (the end user), as opposed to the customer, who pays for it. For example, an employee using a company-paid phone plan. Type: `object` - `address` (`object`, optional, deprecated) — Deprecated. Use `serviceAddress` on each subscription instead. The service address of the oldest subscription of the subscriber. A subscriber with two subscriptions can hold two service addresses, and this field shows only one. — 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. - `contactNumber` (`string`, optional, phone, personal data, example +15551234567) — A phone number for reaching the subscriber, separate from the number their subscription provides. - `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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Optional email address of the subscriber. - `name` (`string`, required, example John Doe) — The full name of the subscriber. - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier of the subscriber. - `subscriptions` (`array of Subscription`, optional) — List of subscriptions associated with the subscriber. Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions. - `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. ## [Subscription](/end-user-api/models#models/Subscription) A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. Type: `object` - `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. ## [SubscriptionAction](/end-user-api/models#models/SubscriptionAction) A subscription operation and its execution state. Action payloads and internal task details are not exposed. Type: `object` - `actionId` (`string`, required) — Unique identifier for this action. - `applyAt` (`string`, required, date-time) — When the operation is scheduled to take effect. - `createdAt` (`string`, required, date-time) — When the action was created. - `customerId` (`string`, required) — Customer that owns the subscription. - `executionFinishedAt` (`string`, optional, date-time) — When execution ended, if it has finished. - `executionStartedAt` (`string`, optional, date-time) — When execution began, if it has started. - `scheduleMode` (`enum`, required, one of UNKNOWN, IMMEDIATE, AT_SPECIFIED_DATE, AT_SPECIFIED_DATE_TIME, ON_DEMAND, example ON_DEMAND) — How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values. - `status` (`enum`, required, one of UNKNOWN, PENDING, RUNNING, SUCCESS, FAILURE, example PENDING) — The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values. - `subscriptionId` (`string`, required) — Subscription affected by this action. - `type` (`enum`, required, one of UNKNOWN, CREATE, CREATE_WITH_PORT_IN, CHANGE_PRODUCT, CHANGE_SIM_CARD, CHANGE_VANITY_NUMBER_FORWARD, CHANGE_MSISDN, CHANGE_MSISDN_WITH_PORT_IN, GET_NEW_MSISDN, CHANGE_RATE_PLAN, PAUSE, SUSPEND, BAR, RESTORE, CANCEL, RESET_NETWORK, ENABLE_ADDON, CANCEL_ADDON, CHANGE_ADDON_PRODUCT, EXPIRE_ADDON, MOVED_FROM_ANOTHER_CUSTOMER, CANCEL_DEVICE_LOCATION, RESET_VOICEMAIL_PASSWORD, UPDATE_ROAMING_LIMIT, ENABLE_VOWIFI, RESEND_ESIM_QR_CODE, RECONNECT, CHANGE_E911_ADDRESS, TOPUP, MOVE_TO_ANOTHER_CUSTOMER, OPEN_FOR_OUTPORTING, ADD_CONTRACT_PERIOD, LEGACY_UPDATE, example ENABLE_VOWIFI) — The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values. - `updatedAt` (`string`, required, date-time) — When the action was most recently updated. ## [SubscriptionActionScheduleMode](/end-user-api/models#models/SubscriptionActionScheduleMode) How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values. Type: `enum` ## [SubscriptionActionStatus](/end-user-api/models#models/SubscriptionActionStatus) The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values. Type: `enum` ## [SubscriptionActionType](/end-user-api/models#models/SubscriptionActionType) The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values. Type: `enum` ## [SubscriptionAddon](/end-user-api/models#models/SubscriptionAddon) An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan. Type: `object` - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the add-on was canceled (if applicable). - `expiredAt` (`string`, optional, date-time, example 2024-07-15T00:00:00Z) — The date and time when the add-on expired (if applicable). - `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. - `license` (`object`, optional) — Essential license information without sensitive details. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the license was activated. - `assignedTo` (`object`, required) — The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription. - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `customer` (`object`, optional) — 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. - `licenseId` (`string`, required, example b3c4d5e6-f7a8-9012-3456-789012345678) — The unique identifier for the license. - `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. - `status` (`enum`, required, one of PENDING, ACTIVE, PAUSED, CANCELLED, BLOCKED) — Current stage of the license lifecycle. - PENDING: Created but not yet activated - ACTIVE: Active and billable; the licensed feature is available - PAUSED: Temporarily stopped; the licensed feature is disabled - CANCELLED: Permanently terminated - BLOCKED: Disabled by the operator, typically for policy or payment reasons - `type` (`string`, optional, example PBX_USER_LEVEL) — The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client), `PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing features), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform. - `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) - `pendingProductOffering` (`object`, optional) — A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date. - `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. - `scheduledAt` (`string`, optional, 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. 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`, optional, one of PENDING, ACTIVE, CANCELLED, EXPIRED) — The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active - `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 telna-package-12345) — A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider. - `status` (`enum`, required, one of PENDING, ACTIVE, CANCELLED, EXPIRED) — The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active - `subscriptionAddonId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the subscription add-on. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription this add-on belongs to. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. ## [SubscriptionAddonListItem](/end-user-api/models#models/SubscriptionAddonListItem) An add-on attached to a subscription, as returned inside subscription list responses. Carries the essentials for showing the add-on alongside its subscription; fetch the add-on individually for the full detail. Type: `object` - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the add-on was canceled (if applicable). - `licenseId` (`string`, optional, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier of the license associated with this add-on (if applicable). - `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) - `productOfferingGroupId` (`string`, optional, example extra-data-packages) — The unique identifier for the product offering group. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. - `referenceId` (`string`, optional, max length 255, example telna-package-12345) — A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider. - `status` (`enum`, required, one of PENDING, ACTIVE, CANCELLED, EXPIRED) — The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. ## [SubscriptionAddonStatus](/end-user-api/models#models/SubscriptionAddonStatus) The status of an add-on on a subscription. - PENDING: Add-on is scheduled but not yet active - ACTIVE: Add-on is currently active and billable - CANCELLED: Add-on has been cancelled and is no longer active - EXPIRED: Add-on has expired and is no longer active Type: `enum` ## [SubscriptionChangeLineItem](/end-user-api/models#models/SubscriptionChangeLineItem) Line item that changes an existing subscription. The changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item. Type: `object` - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription. The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `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) - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `simChange` (`object`, optional) — The SIM card change. Give this value only for changeType SIM_CHANGE. — A change of the SIM card of a subscription. The change carries a one-time price. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. ## [SubscriptionEsimProfile](/end-user-api/models#models/SubscriptionEsimProfile) The live eSIM profile status of a subscription's SIM, reported by the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device. Type: `object` - `eid` (`string`, optional, example 89049032004008882600009B40002780) — The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated. - `installedCount` (`integer`, optional, example 3) — The number of times a device installed this profile. Absent when the network operator sets no limit. - `lastOperationAt` (`string`, optional, date-time, example 2024-06-15T14:30:00Z) — When the last eUICC operation occurred for this profile. - `maxCount` (`integer`, optional, example 5) — The maximum number of times a device can install this profile. Absent when the network operator sets no limit. - `status` (`enum`, required, one of AVAILABLE, ALLOCATED, LINKED, CONFIRMED, RELEASED, DOWNLOADED, INSTALLED, ENABLED, DISABLED, ERROR, UNAVAILABLE, DELETED) — The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription this eSIM profile belongs to. ## [SubscriptionLineItem](/end-user-api/models#models/SubscriptionLineItem) Create a new subscription in this order. This will set up a new phone service for a customer with their chosen plan and phone number. Type: `object` - `activateOnDemand` (`boolean`, optional, example true) — Whether the subscription waits for the subscriber to activate it rather than being activated on a date. The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time. Cannot be combined with scheduleActivationAt. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `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`, optional, personal data, example +15551234567) — The phone number for this subscription. - Leave empty to have one assigned. - When the number pool is available, you can choose a number from the pool and provide the leaseToken. - When porting a number, provide the number and porting details. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — 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. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `sim` (`object`, optional) — The choice between eSIM and physical SIM plus related device details. This value is optional while the order is a draft. You must give it before you submit the order. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — Deprecated. Use `state` on the order. An order fulfills all its line items or none of them, so every line item of an order reports what the order's own `state` already gives you. — The fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriber` (`object`, optional) — The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at 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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `tempNumber` (`boolean`, optional, example true) — Whether to use a temporary number until the porting is completed. If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized. Can only be used when porting in a number (i.e., when msisdn and porting details are provided). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. ## [SubscriptionListItem](/end-user-api/models#models/SubscriptionListItem) Simplified subscription representation optimized for list operations. Use the detailed Subscription schema for individual subscription views. Type: `object` - `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. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer who owns this subscription. - `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, 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. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering associated with this subscription. - `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 - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier for the subscriber associated with this subscription. - `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. ## [SubscriptionPlanChange](/end-user-api/models#models/SubscriptionPlanChange) A change of the product of a subscription. Type: `object` - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. ## [SubscriptionServiceAddress](/end-user-api/models#models/SubscriptionServiceAddress) 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. Type: `object` - `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. ## [SubscriptionSimChange](/end-user-api/models#models/SubscriptionSimChange) A change of the SIM card of a subscription. The change carries a one-time price. Type: `object` - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. ## [SubscriptionStatus](/end-user-api/models#models/SubscriptionStatus) 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: `enum` ## [SubscriptionType](/end-user-api/models#models/SubscriptionType) 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. Type: `string` ## [TaxBreakdownItem](/end-user-api/models#models/TaxBreakdownItem) A single tax or fee contributing to the total tax on a charge, such as state sales tax or a regulatory fee. Type: `object` - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `rate` (`number`, optional, decimal, example 8.25) — The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based. ## [TechnologyCoverage](/end-user-api/models#models/TechnologyCoverage) Coverage details for a single network technology (such as 4G or 5G) at a checked location. Type: `object` - `available` (`boolean`, required, example true) — Whether this technology is available at the checked location. ## [TokenResponse](/end-user-api/models#models/TokenResponse) OAuth2-compatible token response containing the access token for authenticating API requests. Type: `object` - `accessToken` (`string`, required, example ) — JWT access token for authenticating API requests. Include in the Authorization header as "Bearer {accessToken}". - `expiresIn` (`integer`, required, example 604800) — Number of seconds until the access token expires. - `tokenType` (`enum`, required, one of Bearer, example Bearer) — The type of token issued. Always "Bearer" for JWT tokens. - `userId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the authenticated user. ## [USPortOutPin](/end-user-api/models#models/USPortOutPin) A PIN that a subscriber gives to a new carrier to move a US number away. Type: `object` - `expiresAt` (`string`, required, date-time) — When the PIN stops working. - `pin` (`string`, required, personal data) — The 6-digit port-out PIN. Treat it as a credential. ## [USPortOutPinState](/end-user-api/models#models/USPortOutPinState) The US port-out state of a subscription. Type: `object` - `activePin` (`object`, optional) — The active PIN. It is absent when the subscription has no active PIN. — A PIN that a subscriber gives to a new carrier to move a US number away. - `expiresAt` (`string`, required, date-time) — When the PIN stops working. - `pin` (`string`, required, personal data) — The 6-digit port-out PIN. Treat it as a credential. - `portOutProtection` (`object`, optional) — Present while the number is in its port-out protection period after activation. The subscription can get a PIN in this period, but a port-out request with the PIN fails. — The port-out protection of a new number. During the protection period, a new carrier cannot port out the number, even with a valid PIN. Support can open the number for port-out before the period ends. - `portableFrom` (`string`, optional, date, example 2026-10-28) — The first day that a new carrier can port out the number. It is absent when the subscription has no activation date. Then only support can open the number for port-out. - `portable` (`boolean`, required) — False when the subscription cannot port out, for example during a binding period. The PIN is then hidden, and no PIN can be generated. ## [USPortOutProtection](/end-user-api/models#models/USPortOutProtection) The port-out protection of a new number. During the protection period, a new carrier cannot port out the number, even with a valid PIN. Support can open the number for port-out before the period ends. Type: `object` - `portableFrom` (`string`, optional, date, example 2026-10-28) — The first day that a new carrier can port out the number. It is absent when the subscription has no activation date. Then only support can open the number for port-out. ## [UpdateCustomerRequest](/end-user-api/models#models/UpdateCustomerRequest) The customer fields to change. Only provided fields are updated; omitted fields keep their current values. Type: `object` - `billing` (`object`, optional) — Billing details for the customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, example false) — Whether to automatically pay invoices for this customer if a valid payment method is available. - `currency` (`string`, optional, example USD) — The currency for the customer billing. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `defaultPaymentProfileId` (`string`, optional, example m47ac10b-58cc-4372-a567-0e02b2c3d479) — Default payment profile to use for automatic payments and new orders. Must be a valid payment profile owned by this customer. Set to null to disable automatic payments. - `email` (`string`, optional, email, personal data, example billing@example.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, optional, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, optional) — Contact details for the customer. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — The primary contact phone number for the customer. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `name` (`string`, optional, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API. - `preferredLocale` (`string`, optional, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `shippingAddress` (`object`, optional) — The address where the customer gets physical goods, such as SIM cards or devices. Give it only when it is different from the billing address. A customer with no shipping address gets a delivery at 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. - `userIds` (`array of string`, optional) — User IDs to associate with this customer, in addition to those already associated. Depending on the user's role they will either be a member of the customer or given access to manage it. To remove a user, use the remove-user endpoint instead. ## [UpdateOrderRequest](/end-user-api/models#models/UpdateOrderRequest) Request to update order details (excludes line items). Type: `object` - `billing` (`object`, optional) — Billing information for an order. For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level. - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no 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. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. - `consents` (`object with string keys`, optional, example {"marketing":"true","termsOfService":"true"}) — The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later. - `*` (`string`, optional) - `customer` (`one of`, optional) — Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer. - One of: `ExistingCustomerById` - `customerId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically. - One of: `AuthenticatedCustomer` - `authenticatedCustomer` (`boolean`, required, example true) — Always true. - One of: `OrderCustomerReference_NewCustomer` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping 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. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. - `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) - `promoCode` (`string`, optional, example STUDENT2024) — Promo code to apply to the order, or an empty string to remove the one it holds. Rejected with `internalCode` 4119 when no promotion has that code, or when it is outside its validity period. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — 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. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `user` (`one of`, optional) — The person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order. - One of: `ExistingUserById` - `userId` (`string`, required, example d47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's internal ID. - One of: `AuthenticatedUser` - `authenticatedUser` (`boolean`, required, example true) — Always true. - One of: `OrderUserReference_NewUser` - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `address` (`object`, optional, deprecated) — Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in `customer` instead. — 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. - `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`, optional, phone, personal data, example +15551234567) — The user's phone number. - `name` (`string`, required, example John Doe) — The user's full name. ## [UpdateSubscriberRequest](/end-user-api/models#models/UpdateSubscriberRequest) Request to update a subscriber's information. Type: `object` - `address` (`object`, optional, deprecated) — Deprecated. Use `changeSubscriptionServiceAddress` instead. The service address of the mobile subscription of the subscriber. The request fails when the subscriber does not have exactly one mobile subscription. — 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. - `contactNumber` (`string`, optional, phone, personal data, example +15551234567) — A phone number for reaching the subscriber, separate from the number their subscription provides. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The email address of the subscriber. - `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) - `name` (`string`, optional, example John Doe) — The full name of the subscriber. ## [UpfrontPayment](/end-user-api/models#models/UpfrontPayment) 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. Type: `object` - `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. ## [Usage](/end-user-api/models#models/Usage) Current usage statistics for a subscription, organized by service type (voice, SMS, MMS, data). Within each service type, usage is broken down into per-package allowance buckets: the base plan's included allowance plus any add-on packages, each reporting used, remaining, and total amounts. A service type is omitted entirely when the subscription has no allowances of that type. Type: `object` - `data` (`object`, optional) — Data usage across all scopes and packages. — Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad). - `national` (`array of UsageDataNationalPackage`, optional) — Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages. - `dataBytesRemaining` (`integer`, required, int64, example 7516192768) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 10737418240) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `rlahBytesRemaining` (`integer`, optional, int64, example 4294967296) — RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains. - `rlahBytesTotal` (`integer`, optional, int64, example 5368709120) — The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance. - `rlahBytesUsed` (`integer`, optional, int64, example 1073741824) — Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageDataRoamingPackage`, optional) — Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages. - `dataBytesRemaining` (`integer`, required, int64, example 4294967296) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 5368709120) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `mms` (`object`, optional) — MMS usage across all scopes and packages. — MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers). - `ild` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance). - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `national` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages. - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent while roaming abroad. - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `sms` (`object`, optional) — SMS usage across all scopes and packages. — SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers). - `ild` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent from the home country to foreign numbers (international long distance). - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `national` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages. - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent while roaming abroad. - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet. - `voice` (`object`, optional) — Voice call usage across all scopes and packages. — Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers). - `ild` (`array of UsageVoiceIldPackage`, optional) — International long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes. - `balanceMinor` (`integer`, optional, int64, example 1550) — Remaining prepaid amount available for international long distance calls, in minor units of the currency given by `currency`. Each ILD call deducts from this balance at the destination's per-minute rate. - `currency` (`string`, optional, example USD) — Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency. - `expiryDate` (`string`, optional, date, example 2025-12-31) — The date the remaining balance expires and can no longer be used. Absent when the balance does not expire. - `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) - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this balance. Present only when the balance comes from an add-on. - `national` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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) - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made while roaming abroad. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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) - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageData](/end-user-api/models#models/UsageData) Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad). Type: `object` - `national` (`array of UsageDataNationalPackage`, optional) — Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages. - `dataBytesRemaining` (`integer`, required, int64, example 7516192768) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 10737418240) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `rlahBytesRemaining` (`integer`, optional, int64, example 4294967296) — RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains. - `rlahBytesTotal` (`integer`, optional, int64, example 5368709120) — The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance. - `rlahBytesUsed` (`integer`, optional, int64, example 1073741824) — Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageDataRoamingPackage`, optional) — Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages. - `dataBytesRemaining` (`integer`, required, int64, example 4294967296) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 5368709120) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageDataNationalPackage](/end-user-api/models#models/UsageDataNationalPackage) A single data allowance bucket for use in the home country — either the base plan's included data or a package granted by an add-on — reporting bytes used and remaining. Also carries the package's RLAH (Roam Like At Home) counters when part of the allowance can be used while roaming in RLAH regions (such as the EU/EEA) at no extra cost. Type: `object` - `dataBytesRemaining` (`integer`, required, int64, example 7516192768) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 10737418240) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `rlahBytesRemaining` (`integer`, optional, int64, example 4294967296) — RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains. - `rlahBytesTotal` (`integer`, optional, int64, example 5368709120) — The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance. - `rlahBytesUsed` (`integer`, optional, int64, example 1073741824) — Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageDataRoamingPackage](/end-user-api/models#models/UsageDataRoamingPackage) A single data allowance bucket for use while roaming abroad — from the base plan's roaming allowance or a dedicated roaming add-on — reporting bytes used and remaining. Type: `object` - `dataBytesRemaining` (`integer`, required, int64, example 4294967296) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 5368709120) — The full data allowance of this package, in bytes. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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) - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageMms](/end-user-api/models#models/UsageMms) MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers). Type: `object` - `ild` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance). - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `national` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages. - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent while roaming abroad. - `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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageMmsPackage](/end-user-api/models#models/UsageMmsPackage) A single MMS allowance bucket — either the base plan's included multimedia message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain. 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) - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsagePackageStatus](/end-user-api/models#models/UsagePackageStatus) Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable Type: `enum` ## [UsageSms](/end-user-api/models#models/UsageSms) SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers). Type: `object` - `ild` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent from the home country to foreign numbers (international long distance). - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `national` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages. - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent while roaming abroad. - `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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageSmsPackage](/end-user-api/models#models/UsageSmsPackage) A single SMS allowance bucket — either the base plan's included message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain. 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) - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageVoice](/end-user-api/models#models/UsageVoice) Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers). Type: `object` - `ild` (`array of UsageVoiceIldPackage`, optional) — International long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes. - `balanceMinor` (`integer`, optional, int64, example 1550) — Remaining prepaid amount available for international long distance calls, in minor units of the currency given by `currency`. Each ILD call deducts from this balance at the destination's per-minute rate. - `currency` (`string`, optional, example USD) — Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency. - `expiryDate` (`string`, optional, date, example 2025-12-31) — The date the remaining balance expires and can no longer be used. Absent when the balance does not expire. - `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) - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this balance. Present only when the balance comes from an add-on. - `national` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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) - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. - `roaming` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made while roaming abroad. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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) - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [UsageVoiceIldPackage](/end-user-api/models#models/UsageVoiceIldPackage) An international long distance (ILD) calling balance. Unlike national and roaming allowances, ILD calling is prepaid as a monetary amount that is drawn down per call, rather than a bucket of minutes. Type: `object` - `balanceMinor` (`integer`, optional, int64, example 1550) — Remaining prepaid amount available for international long distance calls, in minor units of the currency given by `currency`. Each ILD call deducts from this balance at the destination's per-minute rate. - `currency` (`string`, optional, example USD) — Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency. - `expiryDate` (`string`, optional, date, example 2025-12-31) — The date the remaining balance expires and can no longer be used. Absent when the balance does not expire. - `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) - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this balance. Present only when the balance comes from an add-on. ## [UsageVoicePackage](/end-user-api/models#models/UsageVoicePackage) A single voice allowance bucket — either the base plan's included calling allowance or one granted by an add-on — reporting how much call time has been used and how much remains, in seconds. Type: `object` - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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) - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — The status of this package. — Whether a usage package is currently consumable. - ACTIVE: The package is in its validity window and usage draws from it - NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet - EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires. ## [User](/end-user-api/models#models/User) A person who can sign in and manage one or more customers' accounts. Users are distinct from subscribers: a user administers customers and their services, while a subscriber is the end user of a subscription. Type: `object` - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the user was created. - `customers` (`array of EmbeddedCustomer`, optional) — The customers this user is associated with. The user can sign in and act on behalf of each of these customers. - `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. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — The user's email address. This is their sign-in identity — login verification codes are sent to it — and it is used to reach them when they are a customer's contact person. - `identity` (`string`, optional, personal data, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `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`, optional, phone, personal data, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `name` (`string`, required, example John Doe) — The user's full name, shown in account management and used when the user is listed as a customer's contact person. - `referenceId` (`string`, optional, max length 255, example hr-employee-98765) — A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users or to create/retrieve users during order creation. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the user was last updated. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. ## [UserRole](/end-user-api/models#models/UserRole) The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. Type: `enum` ## [ValidateAddressRequest](/end-user-api/models#models/ValidateAddressRequest) Request to validate an address. Type: `object` - `address` (`object`, required) — The address to validate. The platform does not store it. — 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. - `purpose` (`enum`, optional, default SERVICE, one of SERVICE, POSTAL) — What the address is for. The purpose selects the rules that the address must obey. - `SERVICE`: the address where a line is used. On a US brand, it is the emergency (E911) address of the line. The platform applies the rules of the network operator, and can refuse a PO box. - `POSTAL`: an address that only gets post, for example the address that a SIM card goes to. The platform applies only the address format of the country that the brand serves, and accepts a PO box. If you do not send a purpose, the platform uses `SERVICE`. ## [VerifyEmailLoginRequest](/end-user-api/models#models/VerifyEmailLoginRequest) Request to verify an email login by providing the verification code sent to the email address. Type: `object` - `code` (`string`, required, pattern ^[0-9]{6}$, example 123456) — The 6-digit verification code sent to the email address. - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email address used to initiate the login. - `nonce` (`string`, required, example a1b2c3d4-e5f6-7890-abcd-ef1234567890) — The nonce returned from the start login request.