--- title: Schemas description: Every request, response and webhook payload schema in the API. --- # Schemas Every request, response and webhook payload schema in the API. ## [InvoiceLineItem](/api-reference/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. - `subscriptionId` (`string`, optional, example b8174435-6378-4be5-a9f5-8b4aaadae5d4) — ID of the subscription this line item is associated with, if applicable. - `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. - `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). - `subtotalMinor` (`integer`, required, int64, example 2999) — Line item subtotal (quantity x unitPriceMinor), in minor currency units. - `totalMinor` (`integer`, required, int64, example 3739) — Line item total after taxes, fees, and discounts, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — Tax breakdown for this line item. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example false) — Whether taxes are included in the total. - `fees` (`array of object`, optional) — Detailed fee breakdown for this line item. - `name` (`string`, required, example Late payment fee) — Fee name or description. - `amountMinor` (`integer`, required, int64, example 1000) — Fee amount, in minor currency units. - `totalFeesMinor` (`integer`, optional, int64, example 1000) — Total fees for this line item, in minor currency units. - `discounts` (`array of object`, optional) — Detailed discount breakdown for this line item. - `name` (`string`, required, example Volume discount) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 500) — Discount amount (positive value), in minor currency units. - `totalDiscountsMinor` (`integer`, optional, int64, example 500) — Total discounts for this line item, in minor currency units. ## [StartEmailLoginRequest](/api-reference/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, example john.doe@example.com) — The email address to send the verification code to. ## [StartEmailLoginResponse](/api-reference/models#models/StartEmailLoginResponse) Response from initiating an email login. Contains the nonce needed for verification and timing information. Type: `object` - `nonce` (`string`, required, example a1b2c3d4-e5f6-7890-abcd-ef1234567890) — Token to reference this authentication request during verification. - `expiresIn` (`integer`, required, example 300) — Number of seconds until the verification code expires. - `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. ## [Any](/api-reference/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` ## [Error](/api-reference/models#models/Error) The error body returned by every endpoint when a request fails. Use `internalCode` for programmatic handling, show `message` to a human, and check `details` for field-level problems when the request was invalid. Type: `object` - `message` (`string`, required, example The requested customer could not be found.) — A human-readable message providing more details about the error. - `code` (`string`, required, deprecated, example not_found) — Deprecated. Use `internalCode`. This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it. - `internalCode` (`string`, optional, example 4009) — Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status. - `details` (`array of object`, optional) — Additional details about the error, typically one entry per invalid field on validation failures. - `message` (`string`, required, example Email format is invalid.) — A human-readable message providing more details about the error. - `code` (`string`, required, example invalid_email) — A machine-readable code for the specific detail. - `property` (`string`, optional, example contact.email) — The property or field related to the error. May be nested using dot notation (e.g., "billing.email"). - `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` - `hint` (`string`, optional, example Verify the customerId and try again.) — A hint to help resolve the error. - `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. - `spanId` (`string`, optional, example 37cec694d3b99f0f) — The span within the trace that failed. ## [VerifyEmailLoginRequest](/api-reference/models#models/VerifyEmailLoginRequest) Request to verify an email login by providing the verification code sent to the email address. Type: `object` - `email` (`string`, required, email, 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. - `code` (`string`, required, pattern ^[0-9]{6}$, example 123456) — The 6-digit verification code sent to the email address. ## [TokenResponse](/api-reference/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}". - `tokenType` (`enum`, required, one of Bearer, example Bearer) — The type of token issued. Always "Bearer" for JWT tokens. - `expiresIn` (`integer`, required, example 604800) — Number of seconds until the access token expires. - `userId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the authenticated user. ## [Identity](/api-reference/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` ## [EmbeddedCustomer](/api-reference/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. ## [Metadata](/api-reference/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) ## [User](/api-reference/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` - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. - `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. - `email` (`string`, optional, email, 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. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `identity` (`string`, optional, 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. - `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. - `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. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the user was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the user was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [Pagination](/api-reference/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. ## [CreateUserRequest](/api-reference/models#models/CreateUserRequest) The details needed to create a user and associate them with a customer they can manage. Type: `object` - `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. - `email` (`string`, required, email, example john.doe@example.com) — The user's email address. This becomes their sign-in identity — login verification codes are sent to it. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `role` (`enum`, optional, default MEMBER, one of MEMBER, MANAGER, ADMIN) — The role of the user when assigned to a customer. Defaults to 'MEMBER' if not specified. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer to whom the user will belong. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `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 by your external identifier. - `identity` (`string`, optional, 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) ## [UpdateUserRequest](/api-reference/models#models/UpdateUserRequest) The user fields to change. Only provided fields are updated; omitted fields keep their current values. Type: `object` - `name` (`string`, optional, 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. - `email` (`string`, optional, email, example john.doe@example.com) — The user's email address. This is their sign-in identity — changing it changes where login verification codes are sent. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person. - `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) ## [CustomerType](/api-reference/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` ## [CustomerBillingMethod](/api-reference/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` ## [Address](/api-reference/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` - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [Currency](/api-reference/models#models/Currency) The three-letter ISO 4217 code of the currency used for prices, billing, and payments. Type: `string` ## [UserRole](/api-reference/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` ## [EmbeddedCustomerUser](/api-reference/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` - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `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. ## [Shipping](/api-reference/models#models/Shipping) Shipping information for order fulfillment. Only required if the order contains shippable items. Type: `object` - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. ## [Customer](/api-reference/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` - `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. - `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. - `identity` (`string`, optional, 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. - `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"). - `humanReadableId` (`string`, optional, example 29A-BY3Z-X78) — A human-readable identifier for the customer that customers can state in support requests. - `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. - `contact` (`object`, required) — Contact details for the customer. - `email` (`string`, optional, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the customer. - `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. - `email` (`string`, optional, email, example billing@company.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Required if billing method is PAPER_INVOICE. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `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. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `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. - `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. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `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. - `shipping` (`object`, optional) — The shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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) ## [ShippingInput](/api-reference/models#models/ShippingInput) Shipping information for order fulfillment. Only required if the order contains shippable items. Type: `object` - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. ## [CreateCustomerRequest](/api-reference/models#models/CreateCustomerRequest) The details needed to create a customer: who they are, how to reach them, how they should be billed, and which users can manage the account. 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. - `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. - `identity` (`string`, optional, 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. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the customer. Must be unique per tenant. - `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"). - `contact` (`object`, required) — Contact details for the customer. - `email` (`string`, required, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, required) — Billing configuration and payment preferences for the customer. - `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. - `email` (`string`, optional, email, example billing@company.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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 l47ac10b-58cc-4372-a567-0e02b2c3d479) — Default payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `userIds` (`array of string`, required) — List of user IDs to associate with this customer. Depending on the user's role they will either be a member of the customer or given access to manage it. - `contactPersonUserId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The user ID of the contact person for this customer. This user will be set as the primary contact for the customer and will receive important notifications. - `shipping` (`object`, optional) — The default shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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) ## [UpdateCustomerRequest](/api-reference/models#models/UpdateCustomerRequest) The customer fields to change. Only provided fields are updated; omitted fields keep their current values. Type: `object` - `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. - `identity` (`string`, optional, 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. - `preferredLocale` (`string`, optional, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `contact` (`object`, optional) — Contact details for the customer. - `email` (`string`, optional, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, optional) — Billing details for the customer. - `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. - `email` (`string`, optional, email, example billing@example.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Required if billing method is PAPER_INVOICE. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `autoPay` (`boolean`, optional, example false) — Whether to automatically pay invoices for this customer if a valid payment method is available. - `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. - `shippingAddress` (`object`, optional) — The shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [ProductCategory](/api-reference/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_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription Type: `enum` ## [ProductOfferingGroup](/api-reference/models#models/ProductOfferingGroup) A product group organizes related product offerings. Type: `object` - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. ## [ProductType](/api-reference/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` ## [EmbeddedProduct](/api-reference/models#models/EmbeddedProduct) Embedded representation of a product. Type: `object` - `productId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-890123456789) — The unique identifier for the product. - `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. - `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. - `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_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `networkProviderId` (`string`, optional, example tmobile-us) — The unique identifier for the network provider. - `features` (`object`, optional) — The features included with the product, if any. Typically used for telecom products. - `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. - `validityDays` (`integer`, optional, example 30) — Number of days the product is valid for. 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. - `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. - `activationType` (`enum`, optional, one of INSTANT, FIRST_USE, example INSTANT) — How the travel eSIM package activates. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `simCardType` (`enum`, optional, one of PSIM, ESIM, example PSIM) — The SIM format for a SIM card product. ## [PriceType](/api-reference/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` ## [Duration](/api-reference/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. ## [PriceDiscount](/api-reference/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. - `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. - `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. ## [BindingContract](/api-reference/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` - `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. - `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. - `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. - `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. ## [UpfrontPayment](/api-reference/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. - `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. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. ## [BillingCycle](/api-reference/models#models/BillingCycle) How often a recurring price is charged. Type: `object` - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. ## [Price](/api-reference/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` - `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. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) ## [ProductOffering](/api-reference/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` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the product offering. - `status` (`enum`, required, one of AVAILABLE, ARCHIVED, example AVAILABLE) — 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. - `name` (`string`, required, example Seamless 10GB) — Name of the product offering. - `description` (`string`, optional, example Basic mobile plan with 5GB data and unlimited calls) — Description of 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. - `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. - `product` (`object`, required) — Embedded representation of a product. - `productId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-890123456789) — The unique identifier for the product. - `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. - `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. - `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_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `networkProviderId` (`string`, optional, example tmobile-us) — The unique identifier for the network provider. - `features` (`object`, optional) — The features included with the product, if any. Typically used for telecom products. - `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. - `validityDays` (`integer`, optional, example 30) — Number of days the product is valid for. 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. - `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. - `activationType` (`enum`, optional, one of INSTANT, FIRST_USE, example INSTANT) — How the travel eSIM package activates. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `simCardType` (`enum`, optional, one of PSIM, ESIM, example PSIM) — The SIM format for a SIM card product. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `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. - `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. - `internalDescription` (`string`, optional, example seamless_cell_10gb_us) — Internal description of the product offering for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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) ## [SubscriptionStatus](/api-reference/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](/api-reference/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` ## [EmbeddedProductOffering](/api-reference/models#models/EmbeddedProductOffering) Essential information about a product offering — what is being sold and at what price — without the full catalog details. Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. ## [EmbeddedSubscriber](/api-reference/models#models/EmbeddedSubscriber) The person who uses the service on a subscription, as distinct from the customer who pays for it. Type: `object` - `subscriberId` (`string`, required, example d0e1f2a3-b4c5-6789-0123-456789012345) — The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The subscriber's full name. - `email` (`string`, optional, email, example john.doe@example.com) — The subscriber's email address, if one has been provided. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated. ## [PortingStatus](/api-reference/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` ## [PortingDirection](/api-reference/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` ## [EmbeddedPorting](/api-reference/models#models/EmbeddedPorting) Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. Type: `object` - `msisdn` (`string`, required, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number. - `status` (`enum`, required, one of PENDING, IN_PROGRESS, SCHEDULED, COMPLETED, FAILED) — Current status of the porting process. - PENDING: Porting request created but not yet submitted to the carriers - IN_PROGRESS: Request submitted and awaiting a response from the losing carrier - SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date - COMPLETED: The number has been transferred and is active - FAILED: The request was rejected, canceled, or could not be completed - `direction` (`enum`, required, one of INBOUND, OUTBOUND) — The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur. ## [Subscription](/api-reference/models#models/Subscription) A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. Type: `object` - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — Current stage of the subscription lifecycle. - PENDING: Created but not yet activated in the network - ACTIVATED: Active and billable; service is available - BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations - CANCELLED: Permanently terminated - PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled - SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled - `type` (`string`, required, example CELL) — The kind of telecommunications service the subscription provides. Common values include `CELL` (mobile voice/SMS/data), `DATA` (data-only SIM), `MBB` (mobile broadband), `M2M` (machine-to-machine/IoT), and `TRAVEL_ESIM` (travel eSIM for international roaming). Determined by the product offering the subscription was created with. - `display` (`string`, required, example (555) 123-4567) — Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation. - `msisdn` (`string`, required, phone, example +15551234567) — The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number. - `customer` (`object`, required) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `subscriber` (`object`, optional) — The person who uses the service on a subscription, as distinct from the customer who pays for it. - `subscriberId` (`string`, required, example d0e1f2a3-b4c5-6789-0123-456789012345) — The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The subscriber's full name. - `email` (`string`, optional, email, example john.doe@example.com) — The subscriber's email address, if one has been provided. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields provided for custom subscription types. - `*` (`string`, optional) - `sim` (`object`, required) — SIM card information for the subscription. Sensitive details like PUK require separate API calls. Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK. - `esim` (`boolean`, required, example true) — Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware. Only applicable for eSIM. - `iccid` (`string`, optional, example 8901240197155182976) — Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use. - `pendingMsisdn` (`object`, optional) — A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in `msisdn` until the change takes effect. - `msisdn` (`string`, required, phone, example +15559876543) — The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending number change is scheduled to occur. - `pendingStatus` (`object`, optional) — A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled. - `status` (`enum`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — Current stage of the subscription lifecycle. - PENDING: Created but not yet activated in the network - ACTIVATED: Active and billable; service is available - BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations - CANCELLED: Permanently terminated - PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled - SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `pendingProductOffering` (`object`, optional) — A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur. - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `porting` (`object`, optional) — Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. - `msisdn` (`string`, required, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number. - `status` (`enum`, required, one of PENDING, IN_PROGRESS, SCHEDULED, COMPLETED, FAILED) — Current status of the porting process. - PENDING: Porting request created but not yet submitted to the carriers - IN_PROGRESS: Request submitted and awaiting a response from the losing carrier - SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date - COMPLETED: The number has been transferred and is active - FAILED: The request was rejected, canceled, or could not be completed - `direction` (`enum`, required, one of INBOUND, OUTBOUND) — The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable). - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [PortingDetailsUS](/api-reference/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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [PortingDetailsSweden](/api-reference/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, 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. ## [PortingDetails](/api-reference/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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. ## [SubscriptionActivation](/api-reference/models#models/SubscriptionActivation) Configuration and details required to activate a subscription in the telecommunications network. This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services. Type: `object` - `msisdn` (`string`, optional, example +15551234567) — The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier - `leaseToken` (`string`, optional, example lease_abc123def456) — Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. - `porting` (`object`, optional) — Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `sim` (`object`, required) — SIM card technology and configuration for this subscription. - `esim` (`boolean`, required, example true) — Whether this subscription uses eSIM (embedded SIM) technology. - true: Digital eSIM profile will be provisioned to the device - false: Physical SIM card will be used - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card Identifier (ICCID) of an existing SIM card. Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM. - `deliveryAddress` (`object`, optional) — The address a physical SIM card is posted to. An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [CreateSubscriptionRequest](/api-reference/models#models/CreateSubscriptionRequest) Create a new subscription for a customer. **Activation Options:** 1. **Immediate activation**: Provide activation data without scheduleActivationAt 2. **Scheduled activation**: Provide activation data with scheduleActivationAt for future activation 3. **Shell subscription**: Omit activation data to create a subscription that will be activated later **When to use shell subscriptions:** - When activation details are not yet available (e.g., waiting for SIM card delivery) - When activation requires additional approval or processing - When bulk-creating subscriptions for later activation Note: This endpoint is disabled when Seamless OS manages billing. In that case, subscriptions are created through orders. Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering to subscribe to. This controls what type of subscription is being created. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — Optional reference ID to assign to the subscription. Must be unique per tenant. Once set, this value can be used in place of the subscriptionId in path parameters and request bodies across the API. - `activation` (`object`, optional) — Everything needed to bring the subscription online in the mobile network: the phone number (a specific number, a leased number, or empty for automatic assignment), the SIM configuration (eSIM or physical SIM), and optional porting details when the subscriber keeps their existing number from another carrier. **When to provide:** - Provide activation details to have the subscription provisioned in the network — immediately, or on the date given in `scheduleActivationAt` - Omit to create a "shell" subscription that stays in PENDING status until you activate it later via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are not yet known - `msisdn` (`string`, optional, example +15551234567) — The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier - `leaseToken` (`string`, optional, example lease_abc123def456) — Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. - `porting` (`object`, optional) — Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `sim` (`object`, required) — SIM card technology and configuration for this subscription. - `esim` (`boolean`, required, example true) — Whether this subscription uses eSIM (embedded SIM) technology. - true: Digital eSIM profile will be provisioned to the device - false: Physical SIM card will be used - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card Identifier (ICCID) of an existing SIM card. Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM. - `deliveryAddress` (`object`, optional) — The address a physical SIM card is posted to. An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `scheduleActivationAt` (`string`, optional, date, example 2024-01-15) — Date when the subscription should be activated in the network. Only applicable when activation data is provided. If omitted, activation will be immediate or as soon as network resources are available. **Note**: Network availability and porting timelines may affect the exact activation time. This date is a preference, not a guarantee. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John's work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `subscriber` (`object`, required) — Subscriber details for this subscription. - `name` (`string`, required, example John Doe) — The full name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — The email address of the subscriber. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [ActivateSubscriptionRequest](/api-reference/models#models/ActivateSubscriptionRequest) Request to activate a pending subscription in the telecommunications network. Use this endpoint to activate subscriptions that were created as "shells" without initial activation data, or to activate subscriptions that are in a state where network activation is needed. **Activation timing:** - Omit scheduleActivationAt for immediate activation (or as soon as network resources are available) - Provide scheduleActivationAt to schedule activation for a future date Type: `object` - `activation` (`object`, required) — Complete activation configuration required to bring the subscription online in the network. This includes the phone number assignment, SIM card details, and any number porting information. — Configuration and details required to activate a subscription in the telecommunications network. This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services. - `msisdn` (`string`, optional, example +15551234567) — The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier - `leaseToken` (`string`, optional, example lease_abc123def456) — Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. - `porting` (`object`, optional) — Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `sim` (`object`, required) — SIM card technology and configuration for this subscription. - `esim` (`boolean`, required, example true) — Whether this subscription uses eSIM (embedded SIM) technology. - true: Digital eSIM profile will be provisioned to the device - false: Physical SIM card will be used - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card Identifier (ICCID) of an existing SIM card. Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM. - `deliveryAddress` (`object`, optional) — The address a physical SIM card is posted to. An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `scheduleActivationAt` (`string`, optional, date, example 2025-01-01) — Date when the subscription should be scheduled for activation. If not provided, activation will be immediate or as soon as possible based on network availability. **Note**: Network availability and porting timelines may affect exact timing. This date is considered a preference, not a guarantee. The actual activation may occur on or after this date. ## [Porting](/api-reference/models#models/Porting) A request to transfer (port) a phone number between carriers, either into this platform from the subscriber's previous carrier or out to another carrier. Tracks the number, the transfer's progress, and the ownership details required by the carriers involved. Type: `object` - `msisdn` (`string`, required, example +15551234567) — The phone number to be ported, in E.164 format. - `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 - `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. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the porting is scheduled to occur. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The timestamp of the last update to the porting request. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The timestamp when the porting request was created. ## [UpdatePortingRequest](/api-reference/models#models/UpdatePortingRequest) Request to correct or complete the porting details of a subscription's in-progress port-in, for example after the losing carrier rejected the transfer because the owner details did not match. Type: `object` - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. ## [ChangeSubscriptionProductOfferingRequest](/api-reference/models#models/ChangeSubscriptionProductOfferingRequest) Request to change the product offering of a subscription. Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [ProductOfferingChangeSchedule](/api-reference/models#models/ProductOfferingChangeSchedule) The schedule type for when a product offering change can take effect. - INSTANT: Change takes effect immediately - FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month - NEXT_RENEWAL_DAY: Change takes effect on the next renewal date - NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day Type: `enum` ## [ProductOfferingOption](/api-reference/models#models/ProductOfferingOption) A product offering option available for subscription changes with scheduling information. Type: `object` - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `changeSchedule` (`enum`, required, one of INSTANT, FIRST_OF_NEXT_MONTH, NEXT_RENEWAL_DAY, NEXT_PAYMENT_DAY) — The schedule type for when a product offering change can take effect. - INSTANT: Change takes effect immediately - FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month - NEXT_RENEWAL_DAY: Change takes effect on the next renewal date - NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day - `changeScheduleDate` (`string`, required, date, example 2024-02-01) — The date when the product offering change can take effect. ## [SubscriptionAddonStatus](/api-reference/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` ## [LicenseStatus](/api-reference/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](/api-reference/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` ## [EmbeddedAssignedTo](/api-reference/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` - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) ## [EmbeddedLicense](/api-reference/models#models/EmbeddedLicense) Essential license information without sensitive details. Type: `object` - `licenseId` (`string`, required, example b3c4d5e6-f7a8-9012-3456-789012345678) — The unique identifier for the license. - `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. - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `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. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the license was activated. ## [SubscriptionAddon](/api-reference/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` - `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. - `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. - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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 - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `license` (`object`, optional) — Essential license information without sensitive details. - `licenseId` (`string`, required, example b3c4d5e6-f7a8-9012-3456-789012345678) — The unique identifier for the license. - `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. - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `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. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the license was activated. - `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. - `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 - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `pendingProductOffering` (`object`, optional) — A product offering change (upgrade or downgrade) that has been requested 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. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur. - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. - `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). - `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) ## [AddAddonRequest](/api-reference/models#models/AddAddonRequest) Request to add an add-on to a subscription. Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the add-on product offering to add. Use the addon-options endpoint to discover which add-ons are available for the subscription. - `scheduledAt` (`string`, optional, date, example 2024-03-01) — The date when the add-on should be added. If not provided, the add-on will be added immediately or according to the default schedule. - `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) ## [CancelSubscriptionRequest](/api-reference/models#models/CancelSubscriptionRequest) Request to cancel a subscription. Type: `object` - `cancelAt` (`one of`, required) — When the subscription should be cancelled. - One of: `CancelNextDay` - `nextDay` (`boolean`, required, example true) — Cancel the subscription the next day. - One of: `CancelAtBeginningOfNextMonth` - `nextMonth` (`boolean`, required, example true) — Cancel the subscription at the beginning of next month. - One of: `CancelAtDate` - `date` (`string`, required, date, example 2024-02-01) — Cancel the subscription on a specific date. - `churn` (`enum`, optional, one of BETTER_DEAL_PRICE, NOT_HAPPY_MISSING_FUNCTIONS, NOT_HAPPY_COVERAGE_SLA, NOT_HAPPY_COMPLEX_ADMIN, NOT_HAPPY_SUPPORT_ENGAGEMENT, FRAUD, FRAUD_ATTEMPT, TEST_OR_MARKETING, NO_NEED, WRONG_ORDER, OTHER) — Standardized reason for the cancellation used for reporting and analysis. If OTHER is provided, please also provide a comment. - `comment` (`string`, optional, example Switching to a different provider) — Optional comment about the cancellation. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [SuspendSubscriptionRequest](/api-reference/models#models/SuspendSubscriptionRequest) Request to temporarily suspend a subscription. The customer continues to pay but service is disabled. Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Suspend the subscription on a specific date. - `reason` (`string`, optional, example Payment overdue) — Optional reason for the suspension. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [PauseSubscriptionRequest](/api-reference/models#models/PauseSubscriptionRequest) Request to pause a subscription. The customer stops paying and service is disabled. Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [RestoreSubscriptionRequest](/api-reference/models#models/RestoreSubscriptionRequest) Request to restore a suspended, paused, or blocked subscription back to active state. Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Restore the subscription on a specific date. - `allowedCurrentStatuses` (`array of SubscriptionStatus`, optional) — Current statuses from which this request can restore the subscription. If omitted, the request can restore all supported statuses. - `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) ## [ChangeSubscriptionSimRequest](/api-reference/models#models/ChangeSubscriptionSimRequest) Request to change the SIM card (ICC/ICCID) for a subscription. Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Change the SIM card on a specific date. - `icc` (`string`, required, example 89012345678901234567) — The ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile. - `simCardType` (`enum`, required, one of PHYSICAL, ESIM, example PHYSICAL) — The type of SIM card being installed. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [CancelAddonRequest](/api-reference/models#models/CancelAddonRequest) Request to cancel an add-on from a subscription. Type: `object` - `subscriptionAddonId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The identifier of the subscription add-on to cancel. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_telna-package-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `scheduledAt` (`string`, optional, date, example 2024-03-01) — The date when the add-on should be canceled. If not provided, the add-on will be canceled immediately or according to the default schedule. - `reason` (`string`, optional, example No longer needed) — Free-text explanation of why the add-on is being canceled. Stored with the cancellation for audit and reporting; not shown to 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) ## [ChangeAddonRequest](/api-reference/models#models/ChangeAddonRequest) Request to change an existing add-on to a different product offering. Type: `object` - `subscriptionAddonId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The identifier of the subscription add-on to change. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_telna-package-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `productOfferingId` (`string`, required, example addon-data-5gb) — The unique identifier of the new add-on product offering to change to. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen. - `reason` (`string`, optional, example Customer upgrade request) — Free-text explanation of why the add-on is being changed. Stored with the change for audit and reporting; not shown to 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) ## [UsagePackageStatus](/api-reference/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` ## [UsageVoicePackage](/api-reference/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` - `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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `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. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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 - `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. - `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) ## [UsageVoiceIldPackage](/api-reference/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` - `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. - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `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) ## [UsageVoice](/api-reference/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` - `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. - `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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `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. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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 - `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. - `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) - `roaming` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made while roaming abroad. - `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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `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. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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 - `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. - `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) - `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. - `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. - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `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) ## [UsageSmsPackage](/api-reference/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` - `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. - `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 - `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. - `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) ## [UsageSms](/api-reference/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` - `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. - `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. - `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 - `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. - `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) - `roaming` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent while roaming abroad. - `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. - `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 - `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. - `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) - `ild` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent from the home country to foreign numbers (international long distance). - `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. - `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 - `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. - `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) ## [UsageMmsPackage](/api-reference/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` - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) ## [UsageMms](/api-reference/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` - `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. - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) - `roaming` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent while roaming abroad. - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) - `ild` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance). - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) ## [UsageDataNationalPackage](/api-reference/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` - `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. - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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. - `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. - `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. - `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 - `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. - `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) ## [UsageDataRoamingPackage](/api-reference/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` - `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. - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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. - `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 - `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. - `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) ## [UsageData](/api-reference/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. - `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. - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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. - `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. - `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. - `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 - `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. - `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) - `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. - `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. - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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. - `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 - `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. - `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) ## [Usage](/api-reference/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` - `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). - `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. - `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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `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. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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 - `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. - `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) - `roaming` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made while roaming abroad. - `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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `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. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `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 - `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. - `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) - `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. - `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. - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `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) - `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). - `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. - `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. - `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 - `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. - `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) - `roaming` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent while roaming abroad. - `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. - `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 - `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. - `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) - `ild` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent from the home country to foreign numbers (international long distance). - `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. - `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 - `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. - `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) - `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). - `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. - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) - `roaming` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent while roaming abroad. - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) - `ild` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance). - `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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `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. - `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. - `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) - `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. - `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. - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `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. - `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. - `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. - `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 - `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. - `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) - `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. - `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. - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `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. - `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 - `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. - `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) - `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. ## [EsimQrCode](/api-reference/models#models/EsimQrCode) eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL. Type: `object` - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription this QR code belongs to. - `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. - `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) ## [SubscriberListItem](/api-reference/models#models/SubscriberListItem) Simplified representation of a subscriber (the end user of a subscription) optimized for list operations. Use the detailed Subscriber schema for individual subscriber views. Type: `object` - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier of the subscriber. - `name` (`string`, required, example John Doe) — The full name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Optional email address of the subscriber. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer the subscriber belongs to. - `subscriptionIds` (`array of string`, optional) — List of subscriptions ids associated with the subscriber. Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions. - `createdAt` (`string`, optional, date-time, example 2024-01-10T08:00:00Z) — Date and time when the subscriber was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was last updated. ## [Subscriber](/api-reference/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` - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier of the subscriber. - `name` (`string`, required, example John Doe) — The full name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Optional email address of the subscriber. - `contactNumber` (`string`, optional, phone, example +15551234567) — A phone number for reaching the subscriber, separate from the number their subscription provides. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — Current stage of the subscription lifecycle. - PENDING: Created but not yet activated in the network - ACTIVATED: Active and billable; service is available - BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations - CANCELLED: Permanently terminated - PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled - SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled - `type` (`string`, required, example CELL) — The kind of telecommunications service the subscription provides. Common values include `CELL` (mobile voice/SMS/data), `DATA` (data-only SIM), `MBB` (mobile broadband), `M2M` (machine-to-machine/IoT), and `TRAVEL_ESIM` (travel eSIM for international roaming). Determined by the product offering the subscription was created with. - `display` (`string`, required, example (555) 123-4567) — Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation. - `msisdn` (`string`, required, phone, example +15551234567) — The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number. - `customer` (`object`, required) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. - `productOffering` (`object`, optional) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `subscriber` (`object`, optional) — The person who uses the service on a subscription, as distinct from the customer who pays for it. - `subscriberId` (`string`, required, example d0e1f2a3-b4c5-6789-0123-456789012345) — The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The subscriber's full name. - `email` (`string`, optional, email, example john.doe@example.com) — The subscriber's email address, if one has been provided. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — Date and time when the subscriber was last updated. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields provided for custom subscription types. - `*` (`string`, optional) - `sim` (`object`, required) — SIM card information for the subscription. Sensitive details like PUK require separate API calls. Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK. - `esim` (`boolean`, required, example true) — Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware. Only applicable for eSIM. - `iccid` (`string`, optional, example 8901240197155182976) — Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use. - `pendingMsisdn` (`object`, optional) — A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in `msisdn` until the change takes effect. - `msisdn` (`string`, required, phone, example +15559876543) — The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending number change is scheduled to occur. - `pendingStatus` (`object`, optional) — A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled. - `status` (`enum`, required, one of PENDING, ACTIVATED, BLOCKED, CANCELLED, PAUSED, SUSPENDED) — Current stage of the subscription lifecycle. - PENDING: Created but not yet activated in the network - ACTIVATED: Active and billable; service is available - BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations - CANCELLED: Permanently terminated - PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled - SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled - `scheduledAt` (`string`, optional, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `pendingProductOffering` (`object`, optional) — A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur. - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `porting` (`object`, optional) — Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. - `msisdn` (`string`, required, example +15551234567) — The pending phone number that the subscription will be ported in with. This will always be a non-active number. - `status` (`enum`, required, one of PENDING, IN_PROGRESS, SCHEDULED, COMPLETED, FAILED) — Current status of the porting process. - PENDING: Porting request created but not yet submitted to the carriers - IN_PROGRESS: Request submitted and awaiting a response from the losing carrier - SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date - COMPLETED: The number has been transferred and is active - FAILED: The request was rejected, canceled, or could not be completed - `direction` (`enum`, required, one of INBOUND, OUTBOUND) — The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the number porting is scheduled to occur. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable). - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [UpdateSubscriberRequest](/api-reference/models#models/UpdateSubscriberRequest) Request to update a subscriber's information. Type: `object` - `name` (`string`, optional, example John Doe) — The full name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — The email address of the subscriber. - `contactNumber` (`string`, optional, phone, example +15551234567) — A phone number for reaching the subscriber, separate from the number their subscription provides. - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. Changing it schedules an update with the network operator, so the new address becomes the one emergency services receive. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [License](/api-reference/models#models/License) A license represents a permission to use a software product with embedded customer and product offering details. Type: `object` - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `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. - `customer` (`object`, required) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `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. - `type` (`enum`, required, one of SUBSCRIPTION) — The type of assignment - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier for the subscription - `subscriptionDisplay` (`string`, optional, example +1 (555) 123-4567) — Display name for the subscription (typically the phone number) - `details` (`object`, optional) — Additional license details specific to certain license types. - `propertyName` (`any`, optional) — Any additional properties, passed through as given. - `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. - `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 - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending status change is scheduled to occur. - `pendingProductOffering` (`object`, optional) — A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date. - `scheduledAt` (`string`, required, date, example 2024-02-01) — The date when the pending product offering change is scheduled to occur. - `product` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. When `includesTax` is true, this amount is the total the customer pays, and the tax is a part of it. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `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). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of PRODUCT_CATEGORY_SUBSCRIPTION_CELL, PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM, PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND, PRODUCT_CATEGORY_SUBSCRIPTION_M2M, PRODUCT_CATEGORY_TRAVEL_ESIM, PRODUCT_CATEGORY_EXTRA_DATA, PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE, PRODUCT_CATEGORY_ABROAD, PRODUCT_CATEGORY_EXTERNAL_PRODUCT, PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON, PRODUCT_CATEGORY_SIM_CARD, example PRODUCT_CATEGORY_SUBSCRIPTION_CELL) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `activatedAt` (`string`, required, 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 (if applicable). - `pausedAt` (`string`, optional, date, example 2024-03-01) — The date when the license was paused (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) ## [AssignedTo](/api-reference/models#models/AssignedTo) The entity that a license is assigned to. A license is always assigned to a subscription. Type: `one of` - `type` (`enum`, required, one of SUBSCRIPTION) — The type of entity the license is assigned to. - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier of the subscription the license is assigned to. ## [CreateLicenseRequest](/api-reference/models#models/CreateLicenseRequest) Create a new license. The product offering sets the type of the license. A license for an external product is standalone and takes no `assignedTo`. Every other license needs `assignedTo`, and the subscription must belong to the same customer. Type: `object` - `productOfferingId` (`string`, required, example a7b8c9d0-e1f2-3456-7890-bcdef0123456) — The unique identifier for the product offering to subscribe to. The offering sets the type of the license. - `customerId` (`string`, required, uuid, example b8c9d0e1-f2a3-4567-8901-cdef01234567) — The unique identifier for the existing customer who will own this license. - `licenseType` (`string`, optional, deprecated, example PBX_USER_LEVEL) — Deprecated. The product offering sets the type of the license. The platform rejects a value that does not agree with the product offering. — 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. - `assignedTo` (`one of`, optional) — The entity that a license is assigned to. A license is always assigned to a subscription. - `type` (`enum`, required, one of SUBSCRIPTION) — The type of entity the license is assigned to. - `subscriptionId` (`string`, required, example c9a4d8d4-24c0-4164-ac8d-c77c4103b786) — The unique identifier of the subscription the license is assigned to. - `scheduleActivationAt` (`string`, optional, date, example 2024-01-15) — Date when the license must be activated. The platform activates the license today when you omit this date. A date in the past is not permitted. - `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) ## [ChangeLicenseProductOfferingRequest](/api-reference/models#models/ChangeLicenseProductOfferingRequest) Request to change the product offering of a license. Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the license can be changed to. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [CancelLicenseRequest](/api-reference/models#models/CancelLicenseRequest) Request to cancel a license. Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-03-01) — The date when the license should be cancelled. If not provided, the license will be cancelled immediately or according to the default schedule. - `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) ## [ProductCatalogListItem](/api-reference/models#models/ProductCatalogListItem) A product catalog defines a curated set of product offerings for a specific context such as customer segment, region, or sales channel. Type: `object` - `productCatalogId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the product catalog. - `name` (`string`, required, example US Consumer Catalog) — Name of the product catalog. - `description` (`string`, optional, example Product catalog for US consumer customers) — Description of the product catalog. - `extendsDefault` (`boolean`, required) — Whether this catalog extends the default product catalog. When true, the catalog inherits all offerings from the default catalog in addition to its own. - `isDefault` (`boolean`, optional) — Whether this is the default catalog for its customer type. A customer with no catalog of their own is served the default one. - `customerType` (`enum`, optional, one of CONSUMER, BUSINESS) — The kind of customer this catalog serves. Absent on catalogs that have not been assigned a customer type. — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. ## [EmbeddedDiscount](/api-reference/models#models/EmbeddedDiscount) Essential discount information without sensitive details. Type: `object` - `discountId` (`string`, required, example 80df6fdf-c450-406e-948b-f77d4ac1cdb8) — The unique identifier for the discount. - `description` (`string`, required, example 25% Off Summer Promo) — A description of what the discount provides. - `tag` (`string`, optional, example SUMMER25) — A short label or category for the discount. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the discount was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — When the discount was last updated. ## [Promotion](/api-reference/models#models/Promotion) A promotion that applies a discount when the promotional code is used. Type: `object` - `promotionId` (`string`, required, example 497f6eca-6276-4993-bfeb-53cbbbba6f08) — The unique identifier for the promotion. - `promoCode` (`string`, required, example SUMMER25) — The promotional code that customers can use to activate this promotion. - `discountPeriodMonths` (`integer`, required, example 12) — The number of months the discount will be applied. - `validFrom` (`string`, optional, date) — When the promotion becomes valid and can be used. If not provided, the promotion is valid immediately. - `validTo` (`string`, optional, date) — When the promotion expires and can no longer be used. If not provided, the promotion does not expire. - `discountId` (`string`, required, example 80df6fdf-c450-406e-948b-f77d4ac1cdb8) — The unique identifier for the discount that this promotion applies to. - `discount` (`object`, required) — Essential discount information without sensitive details. - `discountId` (`string`, required, example 80df6fdf-c450-406e-948b-f77d4ac1cdb8) — The unique identifier for the discount. - `description` (`string`, required, example 25% Off Summer Promo) — A description of what the discount provides. - `tag` (`string`, optional, example SUMMER25) — A short label or category for the discount. - `createdAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When the discount was created. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T14:45:00Z) — When the discount was last updated. ## [OrderState](/api-reference/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` ## [OrderListItem](/api-reference/models#models/OrderListItem) Optimized order representation for list operations. Type: `object` - `orderId` (`string`, required, example ce0539b4-ec57-4709-b72e-47892586d05a) — The unique identifier for the order. - `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 - `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. - `pricing` (`object`, optional) — Summary pricing information for the order. - `totalMinor` (`integer`, required, int64, example 13739) — Final order total including all taxes and fees, in minor currency units. - `currency` (`string`, required, example USD) — ISO 4217 currency code. - `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. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `expiresAt` (`string`, optional, date-time, example 2024-01-22T10:30:00Z) — When the order will expire if not submitted. ## [OrderCustomerType](/api-reference/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` ## [OrderUserReference_NewUser](/api-reference/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` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, 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. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [OrderUserReference](/api-reference/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` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, 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. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [OrderCustomerReference_NewCustomer](/api-reference/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` - `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. - `name` (`string`, required, example Acme Corporation) — Name 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, 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. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `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. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `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) ## [OrderCustomerReference](/api-reference/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` - `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. - `name` (`string`, required, example Acme Corporation) — Name 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, 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. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `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. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `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) ## [OrderBillingInput](/api-reference/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` - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [LineItemSim](/api-reference/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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. ## [OrderLineItemStatus](/api-reference/models#models/OrderLineItemStatus) The current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. Type: `enum` ## [SubscriptionLineItem](/api-reference/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` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [AddonLineItem](/api-reference/models#models/AddonLineItem) Line item for adding an add-on to a subscription. Type: `object` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [ExternalProductLineItem](/api-reference/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` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [ExternalLineItem](/api-reference/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` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [SubscriptionPlanChange](/api-reference/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. ## [SubscriptionSimChange](/api-reference/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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. ## [SubscriptionChangeLineItem](/api-reference/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` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [AddonPlanChange](/api-reference/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. ## [AddonChangeLineItem](/api-reference/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` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [OrderLineItem](/api-reference/models#models/OrderLineItem) A line item in an order representing a billable action or service. Type: `one of` - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [Consents](/api-reference/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) ## [CreateOrderRequest](/api-reference/models#models/CreateOrderRequest) Request to create a new order. Orders can be created with minimal information and progressively configured. User and customer information can be added later, including through mid-flow authentication. Type: `object` - `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. - `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` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, 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. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `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` - `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. - `name` (`string`, required, example Acme Corporation) — Name 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, 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. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `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. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `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) - `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. - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `lineItems` (`array of OrderLineItem`, optional) — Initial line items for the order (can be empty). - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - `consents` (`object with string keys`, optional, example {"termsOfService":"true","marketing":"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) - `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. - `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) ## [OrderUserResult](/api-reference/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` - `userId` (`string`, optional, example c47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's identifier, once the user exists. - `name` (`string`, optional, example John Doe) — The user's full name. - `email` (`string`, optional, email, example john.doe@example.com) — The email the user logs in with. - `newUser` (`boolean`, required, example true) — Whether this user is created as part of fulfilling the order. ## [OrderCustomerResult](/api-reference/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. ## [OrderBilling](/api-reference/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` - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [OrderPricingSummary](/api-reference/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` - `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. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `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. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, 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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, 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. - `period` (`object`, optional) — Period covered by the initial invoice. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. ## [TaxBreakdownItem](/api-reference/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` - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. ## [OrderPricingDiscount](/api-reference/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` - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. ## [OrderLineItemPricing](/api-reference/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` - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `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. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, 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. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `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. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. ## [OrderPricing](/api-reference/models#models/OrderPricing) Detailed pricing information for an order including taxes and discounts. Type: `object` - `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. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `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. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, 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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, 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. - `period` (`object`, optional) — Period covered by the initial invoice. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. - `lineItems` (`array of OrderLineItemPricing`, optional) — Pricing breakdown per line item. - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `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. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, 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. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `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. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. ## [InlineValidationError](/api-reference/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` - `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"). ## [OrderRequirement](/api-reference/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` ## [SubscriptionListItem](/api-reference/models#models/SubscriptionListItem) Simplified subscription representation optimized for list operations. Use the detailed Subscription schema for individual subscription views. Type: `object` - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the 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 - `type` (`string`, required, example CELL) — The kind of telecommunications service the subscription provides. Common values include `CELL` (mobile voice/SMS/data), `DATA` (data-only SIM), `MBB` (mobile broadband), `M2M` (machine-to-machine/IoT), and `TRAVEL_ESIM` (travel eSIM for international roaming). Determined by the product offering the subscription was created with. - `display` (`string`, required, example (555) 123-4567) — Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation. - `msisdn` (`string`, required, 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. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer who owns this subscription. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering associated with this subscription. - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier for the subscriber associated with this subscription. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable). - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated. ## [SubscriptionAddonListItem](/api-reference/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` - `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 - `productOfferingGroupId` (`string`, optional, example extra-data-packages) — The unique identifier for the product offering group. - `licenseId` (`string`, optional, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier of the license associated with this add-on (if applicable). - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the add-on was canceled (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) ## [LicenseListItem](/api-reference/models#models/LicenseListItem) Simplified license representation optimized for list operations. The detailed License schema adds the customer and the product offering. Type: `object` - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `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. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering that the license grants. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription that the license is assigned to. Absent for a license that stands alone. - `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. ## [OrderModification](/api-reference/models#models/OrderModification) A modification applied to an existing service during order fulfillment. Type: `object` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE, ADDON_CHANGE) — Type of modification applied. - `targetId` (`string`, required, example e8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription or add-on that was modified. - `newProductOfferingId` (`string`, optional, example po_mobile_premium_plus) — The product offering the entity was changed to. - `appliedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the modification was applied. ## [Order](/api-reference/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` - `orderId` (`string`, required, example order-123) — Unique identifier for the order. - `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 - `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. - `userId` (`string`, optional, example c47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's identifier, once the user exists. - `name` (`string`, optional, example John Doe) — The user's full name. - `email` (`string`, optional, email, example john.doe@example.com) — The email the user logs in with. - `newUser` (`boolean`, required, example true) — Whether this user is created as part of fulfilling the order. - `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. - `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. - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `promoCode` (`string`, optional, example STUDENT2024) — Promotional code applied to this order, if any. - `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. - `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. - `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. - `consents` (`object with string keys`, optional, example {"termsOfService":"true","marketing":"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) - `lineItems` (`array of OrderLineItem`, required) — Line items in the order. - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - `pricing` (`object`, optional) — Detailed pricing information for an order including taxes and discounts. - `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. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `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. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for all pricing amounts (e.g., "USD"). - `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. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, 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. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `initialInvoice` (`object`, optional) — Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, 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. - `period` (`object`, optional) — Period covered by the initial invoice. - `start` (`string`, optional, date, example 2024-01-15) — Start date of the initial billing period. - `end` (`string`, optional, date, example 2024-01-31) — End date of the initial billing period. - `calculatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the pricing was last calculated. - `lineItems` (`array of OrderLineItemPricing`, optional) — Pricing breakdown per line item. - `lineItemId` (`string`, required, example line-item-1) — The line item in the order that this pricing applies to. - `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. - `totalMinor` (`integer`, required, int64, example 2747) — Amount due for this line item after taxes, fees, and discounts, 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. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `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. - `name` (`string`, required, example First month free) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `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. - `totalDiscountsMinor` (`integer`, optional, int64, example 2999) — Total discounts for this line item, in minor currency units. - `description` (`string`, optional, example Premium Plan) — Description of what this line item covers. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `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. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. - `validation` (`object`, required) — Validation status of the order and its line items. - `isValid` (`boolean`, required, example false) — Whether the order is valid and ready for submission. - `missingFields` (`array of string`, optional, example ["customer","billing.address"]) — Required fields that are still missing. - `errors` (`array of InlineValidationError`, optional) — Order-level validation errors. - `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"). - `lineItemValidation` (`array of object`, optional) — Validation status for each line item. - `lineItemId` (`string`, optional, example line-item-1) — Reference to the line item. - `isValid` (`boolean`, optional, example false) — Whether this line item is valid. - `missingFields` (`array of string`, optional, example ["subscriber.name","sim.iccid"]) — Required fields that are still missing. - `errors` (`array of InlineValidationError`, optional) — Validation errors for this line item. - `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"). - `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. - `externalPayment` (`object`, optional) — External payment details if the order was paid outside the system. - `reference` (`string`, optional, example ext-payment-ref-123) — Reference from the external payment 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. - `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). - `submittedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the order was submitted for fulfillment. - `completedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the order was completed. - `createdEntities` (`object`, optional) — Entities created as part of order fulfillment. - `subscriptions` (`array of any`, optional) — Subscriptions created during order fulfillment. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the 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 - `type` (`string`, required, example CELL) — The kind of telecommunications service the subscription provides. Common values include `CELL` (mobile voice/SMS/data), `DATA` (data-only SIM), `MBB` (mobile broadband), `M2M` (machine-to-machine/IoT), and `TRAVEL_ESIM` (travel eSIM for international roaming). Determined by the product offering the subscription was created with. - `display` (`string`, required, example (555) 123-4567) — Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation. - `msisdn` (`string`, required, 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. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer who owns this subscription. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering associated with this subscription. - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier for the subscriber associated with this subscription. - `activatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was activated. Absent until the subscription has been activated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the subscription was cancelled (if applicable). - `createdAt` (`string`, required, date-time, example 2024-01-10T08:00:00Z) — The date and time when the subscription was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — The date and time when the subscription was last updated. - `createdByLineItem` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this subscription. - `addons` (`array of any`, optional) — Add-ons created during order fulfillment. - `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 - `productOfferingGroupId` (`string`, optional, example extra-data-packages) — The unique identifier for the product offering group. - `licenseId` (`string`, optional, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier of the license associated with this add-on (if applicable). - `addedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — The date and time when the add-on was added to the subscription. - `updatedAt` (`string`, optional, date-time, example 2024-01-20T09:00:00Z) — The date and time when the add-on was last updated. - `cancelledAt` (`string`, optional, date-time, example 2024-06-30T00:00:00Z) — The date and time when the add-on was canceled (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) - `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. - `licenseId` (`string`, required, example c9d0e1f2-a3b4-5678-9012-def012345678) — The unique identifier for the license. - `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. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering that the license grants. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription that the license is assigned to. Absent for a license that stands alone. - `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. - `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. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE, ADDON_CHANGE) — Type of modification applied. - `targetId` (`string`, required, example e8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription or add-on that was modified. - `newProductOfferingId` (`string`, optional, example po_mobile_premium_plus) — The product offering the entity was changed to. - `appliedAt` (`string`, optional, date-time, example 2024-01-15T15:00:00Z) — When the modification was applied. - `createdByLineItem` (`string`, required, example i47ac10b-58cc-4372-a567-0e02b2c3d479) — Line item ID that created this modification. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [UpdateOrderRequest](/api-reference/models#models/UpdateOrderRequest) Request to update order details (excludes line items). Type: `object` - `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` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, 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. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `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` - `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. - `name` (`string`, required, example Acme Corporation) — Name 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, 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. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `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. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `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. - `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) - `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. - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `consents` (`object with string keys`, optional, example {"termsOfService":"true","marketing":"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) - `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. - `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) ## [AddLineItemRequest](/api-reference/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` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [UpdateLineItemRequest](/api-reference/models#models/UpdateLineItemRequest) Request to update a line item configuration. Type: `object` - `lineItem` (`one of`, required) — A line item in an order representing a billable action or service. - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `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. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `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. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `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. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `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. - `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. - `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. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `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. - `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. - `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. - `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. - `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) - `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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ## [SubmitOrderRequest](/api-reference/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` - `paymentSessionId` (`string`, optional, example a1b2c3d4-e5f6-7890-1234-56789abcdef0) — Reference to completed payment session for orders requiring payment collection. - `paymentProfileSessionId` (`string`, optional, example b2c3d4e5-f6a7-8901-2345-6789abcdef01) — Reference to completed payment profile session for zero-total orders requiring payment method setup. - `signingSessionId` (`string`, optional, example c3d4e5f6-a7b8-9012-3456-789abcdef012) — Reference to completed signing session. - `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. - `reference` (`string`, required, min length 1, example ext-payment-ref-123) — Reference or identifier from the external payment system. - `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. - `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) ## [ApproveOrderRequest](/api-reference/models#models/ApproveOrderRequest) Approve an order that requires admin or manager approval before fulfillment can proceed. Type: `object` - `comment` (`string`, optional, max length 1000, example Approved after reviewing customer credit check) — Optional comment explaining the approval decision. ## [OrderHandoffToken](/api-reference/models#models/OrderHandoffToken) A short-lived token that lets a checkout pick up a draft order that was built elsewhere, for example by a support agent or a chat assistant. Anyone holding the token can view and complete the order, so pass it only to the person the order is for. Type: `object` - `handoffToken` (`string`, required, example oht_f47ac10b58cc4372a5670e02b2c3d479) — The raw handoff token. It is only returned here and cannot be retrieved again; mint a new one if it is lost. - `orderId` (`string`, required, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The order this token hands off. - `expiresAt` (`string`, required, date-time, example 2024-01-15T11:00:00Z) — When the token stops being claimable. The order itself also expires on its own schedule. ## [OrderHandoffClaim](/api-reference/models#models/OrderHandoffClaim) The order a handoff token resolves to. Type: `object` - `orderId` (`string`, required, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The order the token hands off. - `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. ## [InvoiceStatus](/api-reference/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` ## [PaymentProvider](/api-reference/models#models/PaymentProvider) Payment service provider that processes the transaction. Type: `enum` ## [InvoiceListItem](/api-reference/models#models/InvoiceListItem) An invoice summary. Get the invoice to read its related payment intent, payment attempts, and refunds. Type: `object` - `invoiceId` (`string`, required, example 094f10ca-616e-441c-b264-9a2305d6692d) — Unique identifier for the invoice. - `customerId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer this invoice collects payment from. - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one. - `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. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The provider that issued and manages the invoice. — Payment service provider that processes the transaction. - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts. - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft. - `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. - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided. - `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. - `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. - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created. - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated. - `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) ## [PaymentIntentStatus](/api-reference/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` ## [PaymentIntentLineItem](/api-reference/models#models/PaymentIntentLineItem) A single billed item contributing to a payment intent's amount. Type: `object` - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `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. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. ## [PaymentIntentDiscount](/api-reference/models#models/PaymentIntentDiscount) A reduction applied to the payment intent as a whole rather than to one billed line. Type: `object` - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. ## [PaymentAttempt](/api-reference/models#models/PaymentAttempt) A single charge attempt against a payment intent. Type: `object` - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `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. ## [PaymentRefund](/api-reference/models#models/PaymentRefund) A refund issued against a payment intent. Type: `object` - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `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). - `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. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. ## [PaymentIntent](/api-reference/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` - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `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. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `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. - `lineItems` (`array of PaymentIntentLineItem`, required) — The items that make up the collected amount. - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `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. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. - `discounts` (`array of PaymentIntentDiscount`, required) — Reductions applied to the payment intent as a whole rather than to one billed line. - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. - `attempts` (`array of PaymentAttempt`, required) — Charge attempts made against this payment intent, most recent first. - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `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. - `refunds` (`array of PaymentRefund`, required) — Refunds issued against this payment intent. - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `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). - `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. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. ## [Invoice](/api-reference/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` - `invoiceId` (`string`, required, example 123e4567-e89b-12d3-a456-426614174000) — Unique identifier for the invoice. - `customerId` (`string`, required, example 456789ab-cdef-0123-4567-89abcdef0123) — The customer this invoice collects payment from. - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one. - `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. - `subscriptionId` (`string`, optional, example b8174435-6378-4be5-a9f5-8b4aaadae5d4) — ID of the subscription this line item is associated with, if applicable. - `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. - `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). - `subtotalMinor` (`integer`, required, int64, example 2999) — Line item subtotal (quantity x unitPriceMinor), in minor currency units. - `totalMinor` (`integer`, required, int64, example 3739) — Line item total after taxes, fees, and discounts, in minor currency units. - `taxBreakdown` (`array of TaxBreakdownItem`, optional) — Tax breakdown for this line item. - `description` (`string`, required, example Sales Tax) — Human-readable name of the tax or fee, suitable for display on invoices and receipts. - `amountMinor` (`integer`, required, int64, example 240) — The amount charged for this tax component, in minor units of the currency of the transaction. - `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. - `taxAmountMinor` (`integer`, optional, int64, example 240) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example false) — Whether taxes are included in the total. - `fees` (`array of object`, optional) — Detailed fee breakdown for this line item. - `name` (`string`, required, example Late payment fee) — Fee name or description. - `amountMinor` (`integer`, required, int64, example 1000) — Fee amount, in minor currency units. - `totalFeesMinor` (`integer`, optional, int64, example 1000) — Total fees for this line item, in minor currency units. - `discounts` (`array of object`, optional) — Detailed discount breakdown for this line item. - `name` (`string`, required, example Volume discount) — Discount name or description. - `amountMinor` (`integer`, required, int64, example 500) — Discount amount (positive value), in minor currency units. - `totalDiscountsMinor` (`integer`, optional, int64, example 500) — Total discounts for this line item, in minor currency units. - `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. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The provider that issued and manages the invoice. — Payment service provider that processes the transaction. - `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. - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `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. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `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. - `lineItems` (`array of PaymentIntentLineItem`, required) — The items that make up the collected amount. - `description` (`string`, required, example Mobile subscription - Premium Plan) — What this line item represents. - `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. - `includesTax` (`boolean`, optional, example false) — Whether the taxes are a part of `amountMinor` rather than added to it. - `subscriptionId` (`string`, optional, example a8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription this line item is associated with, if any. - `licenseId` (`string`, optional, example ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77) — The license this line item is associated with, if any. - `discounts` (`array of object`, optional) — Discounts applied to this line item. - `description` (`string`, required, example Loyalty discount) — What the discount is for. - `amountMinor` (`integer`, required, int64, example 500) — The discounted amount (positive value), in minor units of the payment intent's currency. - `taxes` (`array of object`, optional) — Taxes applied to this line item. - `description` (`string`, required, example VAT 25%) — The tax component applied (e.g., a named tax and its rate). - `amountMinor` (`integer`, required, int64, example 725) — The tax amount, in minor units of the payment intent's currency. - `discounts` (`array of PaymentIntentDiscount`, required) — Reductions applied to the payment intent as a whole rather than to one billed line. - `description` (`string`, required, example Goodwill credit) — Why the payment intent was reduced. - `amountMinor` (`integer`, required, int64, example 1000) — The positive amount deducted, in minor units of the payment intent currency. - `attempts` (`array of PaymentAttempt`, required) — Charge attempts made against this payment intent, most recent first. - `paymentAttemptId` (`string`, required, example a4da2b04-aa79-4b40-8987-048d6caf118f) — The unique identifier for this charge attempt. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the attempt was charged in (e.g., "USD"). - `result` (`enum`, required, one of SUCCEEDED, FAILED, example SUCCEEDED) — Whether the charge attempt succeeded or failed. - `reason` (`string`, optional, example card_declined) — Failure reason when the attempt did not succeed. - `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. - `refunds` (`array of PaymentRefund`, required) — Refunds issued against this payment intent. - `refundId` (`string`, required, example c014b666-22e4-430e-bb18-9257a383dfe2) — The unique identifier for this refund. - `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). - `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. - `status` (`enum`, required, one of PENDING, SUCCEEDED, FAILED, CANCELED, REQUIRES_ACTION, example SUCCEEDED) — Current stage of the refund. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the refund was created. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date. - `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. - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts. - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft. - `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. - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided. - `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. - `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. - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created. - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated. - `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) ## [MarkInvoiceAsPaidRequest](/api-reference/models#models/MarkInvoiceAsPaidRequest) Request to mark an invoice as paid when you manage your own payment processing. Type: `object` - `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the payment was received. If not provided, uses the current timestamp. - `metadata` (`object with string keys`, optional) — Metadata to attach to the invoice. — 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) ## [PaymentLinkStatus](/api-reference/models#models/PaymentLinkStatus) Current status of a payment link. - ACTIVE: The link is open and the customer can complete payment. - EXPIRED: The link expired before payment was completed. - COMPLETED: Payment through the link succeeded. - CANCELED: The link was canceled and can no longer be used. - FAILED: Payment through the link failed. Type: `enum` ## [PaymentLink](/api-reference/models#models/PaymentLink) A shareable hosted payment page that collects payment for an order at the customer's convenience. Create one when the customer is not in an active checkout flow — for example to send by email or SMS — and anyone with the URL can complete the payment. Use a payment session instead when the customer is present in your checkout and should be redirected to pay immediately. Both collect against the order's underlying payment intent, which records the resulting charges and refunds. Type: `object` - `paymentLinkId` (`string`, required, example j47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the payment link. - `orderId` (`string`, optional, example 44567801-a504-4f09-8089-31ea78bc239b) — The order this payment link collects payment for. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment link collects payment from. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `paymentProfileId` (`string`, optional, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The saved payment method pre-selected for the customer, if any. - `hostedUrl` (`string`, required, uri, example https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479) — The URL where customers can complete their payment. - `status` (`enum`, required, one of ACTIVE, EXPIRED, COMPLETED, CANCELED, FAILED) — Current status of a payment link. - ACTIVE: The link is open and the customer can complete payment. - EXPIRED: The link expired before payment was completed. - COMPLETED: Payment through the link succeeded. - CANCELED: The link was canceled and can no longer be used. - FAILED: Payment through the link failed. - `description` (`string`, optional, example Pay your monthly subscription) — Optional description displayed on the payment page. - `paymentIntentId` (`string`, optional, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The payment intent that collected the payment, available once the link has been paid. - `completedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the payment was completed, if the link has been paid. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment link was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment link was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ## [CreatePaymentLinkRequest](/api-reference/models#models/CreatePaymentLinkRequest) Request to create a new payment link for processing payment for an order or invoice. Either orderId or invoiceId must be provided, not both. Type: `object` - `orderId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the order to create a payment link for. Either orderId or invoiceId must be provided, not both. - `invoiceId` (`string`, optional, example 123e4567-e89b-12d3-a456-426614174000) — The unique identifier of the invoice to create a payment link for. Either orderId or invoiceId must be provided, not both. Invoice payment links are not yet available in all environments. - `paymentProfileId` (`string`, optional, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — A previously saved payment method to prefill on the payment page, for returning customers. - `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. - `description` (`string`, optional, example Payment for Telness mobile subscription) — Optional description to display on the payment page. - `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. - `returnUrl` (`string`, optional, uri, example https://your-domain.com/success) — URL to redirect customers to after successful payment. - `cancelUrl` (`string`, optional, uri, example https://your-domain.com/cancel) — URL to redirect customers to if they cancel the payment. - `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) ## [PaymentIntentType](/api-reference/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` ## [PaymentIntentListItem](/api-reference/models#models/PaymentIntentListItem) A payment intent without its nested attempts, refunds, and line items, optimized for list views. Type: `object` - `paymentIntentId` (`string`, required, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The unique identifier for this payment intent. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment intent collects from. - `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. - `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). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the amount is collected in (e.g., "USD"). - `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. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment intent was last updated. ## [PaymentSessionBranding](/api-reference/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. - `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. - `borderStyle` (`enum`, optional, one of PILL, RECTANGULAR, ROUNDED, example PILL) — The shape of the buttons and the input fields of the payment form. - `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. ## [CreatePaymentSessionRequest](/api-reference/models#models/CreatePaymentSessionRequest) Request to create a new payment session for processing payment for an order. Type: `object` - `orderId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-89abcdef0123) — The unique identifier of the order to create a payment session for. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `paymentProfileId` (`string`, optional, example e5f6a7b8-c9d0-1234-5678-9abcdef01234) — A previously saved payment method to prefill on the payment page, for returning customers. - `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. - `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. - `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. - `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. - `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. - `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. - `borderStyle` (`enum`, optional, one of PILL, RECTANGULAR, ROUNDED, example PILL) — The shape of the buttons and the input fields of the payment form. - `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. - `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) ## [StripeCheckoutContext](/api-reference/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. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. ## [PaymentSessionProviderContext](/api-reference/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. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. ## [PaymentSessionStatus](/api-reference/models#models/PaymentSessionStatus) Current status of a payment session lifecycle. Type: `enum` ## [PaymentSession](/api-reference/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` - `paymentSessionId` (`string`, required, example d2e3f4a5-b6c7-8901-2345-012345678901) — The unique identifier for this payment session. - `orderId` (`string`, required, example e3f4a5b6-c7d8-9012-3456-123456789012) — The unique identifier of the order this payment session is for. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `paymentProfileId` (`string`, optional, example f4a5b6c7-d8e9-0123-4567-234567890123) — The saved payment method to use for this payment (for returning customers). - `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. - `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. - `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. - `publishableKey` (`string`, required, example pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9) — The Stripe publishable key to load Stripe.js with. The key is public. - `connectedAccountId` (`string`, required, example acct_1H8x2vLkdIwHu7ix) — The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account. - `returnUrl` (`string`, optional, example https://example.com/order/confirmation) — The URL the customer is redirected to after payment completion. - `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel the payment. - `status` (`enum`, required, one of PENDING, REQUIRES_ACTION, COMPLETED, FAILED, CANCELED, EXPIRED, example PENDING) — Current status of a payment session lifecycle. - `metadata` (`object with string keys`, required, example {"source":"mobile_app","campaign":"summer_2024"}) — Custom key-value pairs for additional payment session information. - `*` (`string`, optional) - `createdAt` (`string`, required, date-time, example 2024-09-29T10:00:00Z) — When this payment session was created. - `updatedAt` (`string`, required, date-time, example 2024-09-29T10:30:00Z) — When this payment session was last updated. ## [CancelPaymentSessionRequest](/api-reference/models#models/CancelPaymentSessionRequest) Request to cancel an active payment session. Type: `object` - `reason` (`string`, optional, example Customer changed their mind) — Optional reason for cancelling the payment session. - `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) ## [PaymentMethodType](/api-reference/models#models/PaymentMethodType) The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change. Type: `string` ## [PaymentProfileStatus](/api-reference/models#models/PaymentProfileStatus) Whether a saved payment profile can currently be charged. - ACTIVE: The payment method is valid and can be used for payments. - INACTIVE: The payment method has been deactivated and cannot be charged. - EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced. - REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again. Type: `enum` ## [EmbeddedPaymentProfile](/api-reference/models#models/EmbeddedPaymentProfile) A saved payment method with only the details needed to display it in a list, without billing information. Type: `object` - `paymentProfileId` (`string`, required, example f6a7b8c9-d0e1-2345-6789-abcdef012345) — Unique identifier for this payment profile. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `type` (`string`, required, example CARD) — Type of payment method. — The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change. - `status` (`enum`, required, one of ACTIVE, INACTIVE, EXPIRED, REQUIRES_ACTION, example ACTIVE) — Current status of the payment profile. — Whether a saved payment profile can currently be charged. - ACTIVE: The payment method is valid and can be used for payments. - INACTIVE: The payment method has been deactivated and cannot be charged. - EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced. - REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again. - `displayName` (`string`, optional, example Visa ending in 4242) — Human-readable name for the payment method, safe to show to the customer: - Card: "Visa ending in 4242" - SEPA: "Bank account ending in 3000" - Swish: "Swish +46701234567" - `isDefault` (`boolean`, optional, example true) — Whether this is the customer's default payment profile. - `expiresAt` (`string`, optional, date, example 2025-12-31) — When this payment profile expires (for cards). - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When this payment profile was created. ## [PaymentProfile](/api-reference/models#models/PaymentProfile) A saved payment method or mandate for future use. Type: `object` - `paymentProfileId` (`string`, required, example d9f0b83a-8b0d-44a6-af7c-54b6b91b6040) — Unique identifier for this payment profile. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The payment provider for this payment profile. — Payment service provider that processes the transaction. - `type` (`string`, required, example CARD) — Type of payment method. — The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change. - `status` (`enum`, required, one of ACTIVE, INACTIVE, EXPIRED, REQUIRES_ACTION, example ACTIVE) — Current status of the payment profile. — Whether a saved payment profile can currently be charged. - ACTIVE: The payment method is valid and can be used for payments. - INACTIVE: The payment method has been deactivated and cannot be charged. - EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced. - REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — Customer who owns this payment profile. - `displayName` (`string`, optional, example My credit card) — Human-readable name for this payment method. - `expiresAt` (`string`, optional, date, example 2025-12-31) — When this payment profile expires (for cards). - `billingDetails` (`object`, optional) — Billing details associated with this payment method. - `name` (`string`, optional, example John Doe) — Billing name. - `email` (`string`, optional, email, example john.doe@example.com) — Billing email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When this payment profile was created. - `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) ## [CreatePaymentProfileSessionRequest](/api-reference/models#models/CreatePaymentProfileSessionRequest) Request to create a new payment profile session for setting up a saved payment method. Type: `object` - `orderId` (`string`, required, example 9f8e7d6c-5b4a-3210-9876-543210987654) — The unique identifier of the order this payment profile session is associated with. - `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 is redirected to after the payment method is saved. - `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel before saving a payment method. - `setAsDefaultPaymentProfile` (`boolean`, optional, example false) — Whether to set the saved payment method as the customer's default for future payments. Defaults to false. - `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) ## [PaymentProfileSessionStatus](/api-reference/models#models/PaymentProfileSessionStatus) Current status of a payment profile session lifecycle. Type: `enum` ## [PaymentProfileSession](/api-reference/models#models/PaymentProfileSession) A session that walks the customer through setting up and saving a payment method for future billing, without charging them. Create one when an order requires a payment profile but no upfront payment (e.g., a zero-total order), redirect the customer to hostedUrl, and pass the completed session's paymentProfileSessionId when submitting the order. To collect an actual payment, create a payment session instead. Type: `object` - `paymentProfileSessionId` (`string`, required, example 69321a62-f1fe-461f-8761-a19ae6587bb2) — The unique identifier for this payment profile session. - `orderId` (`string`, required, example 44567801-a504-4f09-8089-31ea78bc239b) — The unique identifier of the order this payment profile session is associated with. - `paymentProvider` (`enum`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `status` (`enum`, required, one of PENDING, REQUIRES_ACTION, COMPLETED, FAILED, CANCELED, example PENDING) — Current status of a payment profile session lifecycle. - `hostedUrl` (`string`, required, uri, example https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2) — The hosted page to redirect the customer to in order to save their payment method. - `metadata` (`object with string keys`, required, example {"source":"mobile_app","campaign":"summer_2024"}) — Custom key-value pairs for additional payment profile session information. - `*` (`string`, optional) - `createdAt` (`string`, required, date-time, example 2024-09-29T10:00:00Z) — When this payment profile session was created. - `updatedAt` (`string`, required, date-time, example 2024-09-29T10:30:00Z) — When this payment profile session was last updated. ## [CancelPaymentProfileSessionRequest](/api-reference/models#models/CancelPaymentProfileSessionRequest) Request to cancel an active payment profile session. Type: `object` - `reason` (`string`, optional, example Customer decided not to save payment method) — Optional reason for cancelling the payment profile session. - `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) ## [SigningStatus](/api-reference/models#models/SigningStatus) The current status of a signing session. Type: `enum` ## [SigningSession](/api-reference/models#models/SigningSession) A contract signing session for an order requiring legal signature. Type: `object` - `signingSessionId` (`string`, required, example f7d2295f-0dd4-4ebe-8ec5-de2d0f41be7e) — The unique identifier for this signing session. - `orderId` (`string`, required, example 44567801-a504-4f09-8089-31ea78bc239b) — The order that requires signing. - `status` (`enum`, required, one of PENDING, IN_PROGRESS, COMPLETED, FAILED, EXPIRED, CANCELLED) — The current status of a signing session. - `signerDetails` (`object with string keys`, required, example {"name":"John Doe","email":"john.doe@example.com","identity":"199001011234"}) — Information about the person signing the contract. The specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider. - `*` (`string`, optional) - `provider` (`string`, optional, example bankid) — The signing provider used for this session. - `language` (`string`, optional, default en, example en) — The language used for the signing interface. - `redirectUrl` (`string`, optional, uri, example https://sign.provider.com/session/abc123) — The URL where the user should be redirected to complete signing. - `returnUrl` (`string`, optional, uri, example https://yourapp.com/orders/123/complete) — The URL where the user will be redirected after signing completion. - `documentUrl` (`string`, optional, uri, example https://api.yourapp.com/documents/signed-contract-123.pdf) — Download URL for the signed contract. Only available when status is COMPLETED. - `completedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the signing was completed. Only present when status is COMPLETED. - `expiresAt` (`string`, optional, date-time, example 2024-01-15T23:59:59Z) — When this signing session expires. - `failureReason` (`string`, optional, example User canceled signing process) — The reason for signing failure. Only present when status is FAILED. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the signing session was created. - `metadata` (`object with string keys`, optional, example {"contract_type":"postpaid_subscription","customer_segment":"b2b"}) — Additional metadata for the signing session. - `*` (`string`, optional) ## [CreateSigningSessionRequest](/api-reference/models#models/CreateSigningSessionRequest) Request to create a contract signing session for an order. Type: `object` - `orderId` (`string`, required, example 123e4567-e89b-12d3-a456-426614174000) — The order that requires contract signing. - `signerDetails` (`object with string keys`, required, example {"name":"John Doe","email":"john.doe@example.com","identity":"199001011234"}) — Information about the person who will sign the contract. The specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider. - `*` (`string`, optional) - `returnUrl` (`string`, required, uri, example https://yourapp.com/orders/123/complete) — The URL where the user will be redirected after signing completion or failure. - `provider` (`string`, optional, example bankid) — The preferred signing provider. If not specified, the default provider will be used. - `language` (`string`, optional, default en, example sv) — The language for the signing interface. - `metadata` (`object with string keys`, optional, example {"contract_type":"postpaid_subscription","customer_segment":"b2b"}) — Additional metadata for the signing session. - `*` (`string`, optional) ## [SigningRequirement](/api-reference/models#models/SigningRequirement) Whether a signer detail field is optional or required for a signing provider. - 'OPTIONAL': The field is optional and may be omitted. - 'REQUIRED': The field is required and must be provided. Type: `enum` ## [SigningProvider](/api-reference/models#models/SigningProvider) A signing provider and its requirements for signer details. Type: `object` - `provider` (`string`, required, example bankid) — The unique identifier for the signing provider. - `name` (`string`, required, example BankID) — The display name of the signing provider. - `description` (`string`, optional, example Swedish digital identity verification and signing service) — A brief description of the signing provider and its use cases. - `supportedCountries` (`array of string`, optional, example ["SE"]) — List of country codes where this provider is available. - `supportedLanguages` (`array of string`, optional, example ["sv","en"]) — List of language codes supported by this provider. - `requirements` (`object with string keys`, required, example {"name":"REQUIRED","email":"REQUIRED","identity":"REQUIRED"}) — Information that may or must be collected from the signer before initiating the signing process. Each key represents a field name in the signerDetails object, and the value indicates whether it's optional or required. - `*` (`enum`, optional, one of OPTIONAL, REQUIRED) — Whether a signer detail field is optional or required for a signing provider. - 'OPTIONAL': The field is optional and may be omitted. - 'REQUIRED': The field is required and must be provided. - `capabilities` (`object`, optional) — Additional capabilities and features supported by this provider. - `multipleSigners` (`boolean`, optional, example false) — Whether the provider supports multiple signers on the same document. - `documentTemplates` (`boolean`, optional, example true) — Whether the provider supports custom document templates. - `biometricSigning` (`boolean`, optional, example true) — Whether the provider supports biometric signing methods. ## [ValidateAddressRequest](/api-reference/models#models/ValidateAddressRequest) Request to validate an address. 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ## [AddressValidationResult](/api-reference/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` - `valid` (`boolean`, required, example false) — Whether the provided address is valid. - `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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `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"). ## [CheckPortingEligibilityRequest](/api-reference/models#models/CheckPortingEligibilityRequest) Request to check if a phone number is eligible for porting. Type: `object` - `msisdn` (`string`, required, phone, example +15551234567) — The phone number to check for porting eligibility. ## [PortingEligibilityResult](/api-reference/models#models/PortingEligibilityResult) Result of number porting eligibility check. Type: `object` - `msisdn` (`string`, required, phone, example +15551234567) — The phone number that was checked. - `eligible` (`boolean`, required, example true) — Whether the number is eligible for porting. - `networkProviderId` (`string`, optional, example tmobile-us) — The identifier for the current network provider, if detectable - `ineligibilityReason` (`string`, optional, example Number not found or not portable) — Reason why number is not eligible (only present if eligible is false). ## [GetDeviceInfoRequest](/api-reference/models#models/GetDeviceInfoRequest) Request to get device information by IMEI. Type: `object` - `imei` (`string`, required, example 356938035643809) — The International Mobile Equipment Identity of the device. ## [DeviceInfo](/api-reference/models#models/DeviceInfo) Information about a device based on its IMEI. Type: `object` - `imei` (`string`, required, example 356938035643809) — The device IMEI that was checked. - `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. - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `model` (`string`, optional, example A2653) — Device model. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. ## [SearchDevicesRequest](/api-reference/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` - `query` (`string`, required, min length 2, example iPhone 15) — Part of the device name to match, such as the brand, the model, or both. - `limit` (`integer`, optional, >= 1, <= 50, default 20, example 20) — The largest number of devices to return. ## [DeviceMatch](/api-reference/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` - `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. - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `model` (`string`, optional, example A2653) — Device model. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. ## [DeviceSearchResult](/api-reference/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. - `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. - `esim` (`boolean`, required, example true) — Whether the device supports eSIM. - `manufacturer` (`string`, optional, example Apple) — Device manufacturer. - `model` (`string`, optional, example A2653) — Device model. - `marketingName` (`string`, optional, example iPhone 15 Pro) — Device marketing name. ## [CoverageAddress](/api-reference/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` - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, optional, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, optional, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). ## [CheckNetworkCoverageRequest](/api-reference/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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, optional, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, optional, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). ## [Coordinates](/api-reference/models#models/Coordinates) A geographic location in WGS84 coordinates, the standard used by GPS. Type: `object` - `latitude` (`number`, required, float, example 40.7128) — Latitude in decimal degrees. Positive values are north of the equator. - `longitude` (`number`, required, float, example -74.006) — Longitude in decimal degrees. Negative values are west of the prime meridian. ## [TechnologyCoverage](/api-reference/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. ## [NetworkCoverage](/api-reference/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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, optional, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, optional, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `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. - `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. - `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. - `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, example 40.7128) — Latitude in decimal degrees. Positive values are north of the equator. - `longitude` (`number`, required, float, example -74.006) — Longitude in decimal degrees. Negative values are west of the prime meridian. - `networkProviderId` (`string`, optional, example tmobile-us) — Which network this coverage data applies to. - `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. - `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). ## [NumberType](/api-reference/models#models/NumberType) The service class of a phone number, determining what kind of subscription it can be used for. - CELL: Mobile number for voice, SMS, and data subscriptions - FIXED: Fixed-line (landline) number - DATA: Number for data-only subscriptions - M2M: Number for machine-to-machine/IoT subscriptions Type: `enum` ## [LeaseNumbersRequest](/api-reference/models#models/LeaseNumbersRequest) Request to lease phone numbers for use in orders. Type: `object` - `types` (`array of NumberType`, required, example ["CELL"]) — Types of numbers to lease. - `count` (`integer`, required, >= 1, <= 10, example 2) — Number of phone numbers to lease. ## [LeasedNumber](/api-reference/models#models/LeasedNumber) A phone number that has been leased for use in orders. Type: `object` - `msisdn` (`string`, required, phone, example +15551234567) — The leased phone number. - `type` (`enum`, required, one of CELL, FIXED, DATA, M2M, example CELL) — The service class of a phone number, determining what kind of subscription it can be used for. - CELL: Mobile number for voice, SMS, and data subscriptions - FIXED: Fixed-line (landline) number - DATA: Number for data-only subscriptions - M2M: Number for machine-to-machine/IoT subscriptions - `grade` (`integer`, required, >= 1, <= 10, example 5) — Quality grade of the number (1=premium, 10=standard). - `availableAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When this number became available for leasing. - `leasedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When this number was leased. - `expiresAt` (`string`, required, date-time, example 2024-01-15T11:30:00Z) — When this lease expires if not used in an order. - `metadata` (`object with string keys`, optional, example {"region":"New York","areaCode":"555"}) — Additional number metadata. - `*` (`string`, optional) ## [NumberLeaseResult](/api-reference/models#models/NumberLeaseResult) Result of a number leasing request. Type: `object` - `numbers` (`array of LeasedNumber`, required) — The leased phone numbers. - `msisdn` (`string`, required, phone, example +15551234567) — The leased phone number. - `type` (`enum`, required, one of CELL, FIXED, DATA, M2M, example CELL) — The service class of a phone number, determining what kind of subscription it can be used for. - CELL: Mobile number for voice, SMS, and data subscriptions - FIXED: Fixed-line (landline) number - DATA: Number for data-only subscriptions - M2M: Number for machine-to-machine/IoT subscriptions - `grade` (`integer`, required, >= 1, <= 10, example 5) — Quality grade of the number (1=premium, 10=standard). - `availableAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When this number became available for leasing. - `leasedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — When this number was leased. - `expiresAt` (`string`, required, date-time, example 2024-01-15T11:30:00Z) — When this lease expires if not used in an order. - `metadata` (`object with string keys`, optional, example {"region":"New York","areaCode":"555"}) — Additional number metadata. - `*` (`string`, optional) - `leaseToken` (`string`, required, example lease_abc123def456) — Token to use when creating subscription line items with these numbers. Provide this token in the `leaseToken` field when ordering or creating a subscription along with the chosen `msisdn` from the leased numbers. - `expiresAt` (`string`, required, date-time, example 2024-01-15T11:30:00Z) — When this lease expires if not used in an order. ## [SimType](/api-reference/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` ## [SimStatus](/api-reference/models#models/SimStatus) Current lifecycle status of the SIM card in inventory. - AVAILABLE: In stock and free to be assigned to a subscription - IN_USE: Currently assigned to an active subscription - RESERVED: Held for a pending order or activation - CONSUMED: Used up and no longer assignable (for example a single-use eSIM profile) - BRAND_RESERVED: Set aside for a specific brand and not generally assignable Type: `enum` ## [EsimInstallationStatus](/api-reference/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` ## [EsimProfile](/api-reference/models#models/EsimProfile) Live eSIM profile status from the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device. Type: `object` - `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. - `eid` (`string`, optional, example 89049032004008882600009B40002780) — The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated. - `lastOperationAt` (`string`, optional, date-time, example 2024-06-15T14:30:00Z) — When the last eUICC operation occurred for this profile. - `installedCount` (`integer`, optional, example 3) — The number of times a device installed this profile. Absent when the network operator sets no limit. - `maxCount` (`integer`, optional, example 5) — The maximum number of times a device can install this profile. Absent when the network operator sets no limit. ## [InventorySim](/api-reference/models#models/InventorySim) A SIM card from inventory. For eSIM cards, the response may include live installation status from the network operator when the SIM is linked to a subscription. Type: `object` - `iccid` (`string`, required, example 8946200508271016579) — The ICCID (Integrated Circuit Card Identifier) of the SIM card. - `imsi` (`string`, optional, example 310150000000001) — The IMSI (International Mobile Subscriber Identity) of the SIM. - `type` (`enum`, required, one of PHYSICAL, ESIM) — 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 - `status` (`enum`, required, one of AVAILABLE, IN_USE, RESERVED, CONSUMED, BRAND_RESERVED) — Current lifecycle status of the SIM card in inventory. - AVAILABLE: In stock and free to be assigned to a subscription - IN_USE: Currently assigned to an active subscription - RESERVED: Held for a pending order or activation - CONSUMED: Used up and no longer assignable (for example a single-use eSIM profile) - BRAND_RESERVED: Set aside for a specific brand and not generally assignable - `lpa` (`string`, optional, example 1$rsp.example.com$ABCD1234) — Local Profile Assistant address for eSIM activation. - `esimProfile` (`object`, optional) — Live eSIM profile status from the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device. - `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. - `eid` (`string`, optional, example 89049032004008882600009B40002780) — The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated. - `lastOperationAt` (`string`, optional, date-time, example 2024-06-15T14:30:00Z) — When the last eUICC operation occurred for this profile. - `installedCount` (`integer`, optional, example 3) — The number of times a device installed this profile. Absent when the network operator sets no limit. - `maxCount` (`integer`, optional, example 5) — The maximum number of times a device can install this profile. Absent when the network operator sets no limit. - `createdAt` (`string`, optional, date-time, example 2024-01-10T08:00:00Z) — When the SIM was added to inventory. - `updatedAt` (`string`, optional, date-time, example 2024-06-15T14:30:00Z) — When the SIM was last updated in inventory. ## [EmbeddedWorkflowTask](/api-reference/models#models/EmbeddedWorkflowTask) Essential workflow task information for tracking webhook-triggered workflow executions. Type: `object` - `workflowTaskId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the workflow task. - `name` (`string`, required, example Process Customer Order) — The name of the workflow that was triggered. - `description` (`string`, optional, example Processes new customer orders and initiates fulfillment) — A description of what the workflow task does. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the workflow task was created. ## [ReportRunStatus](/api-reference/models#models/ReportRunStatus) The current stage of a report run in its lifecycle. Type: `enum` ## [ReportRun](/api-reference/models#models/ReportRun) A generated report and its current state. When the report has finished generating, a time-limited download link is provided so the file can be fetched directly. Type: `object` - `reportRunId` (`string`, required, uuid, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for this report run. - `reportKey` (`string`, required, example subscriber_base_and_revenue) — Identifies which report was generated. - `status` (`enum`, required, one of QUEUED, RUNNING, SUCCEEDED, FAILED) — The current stage of a report run in its lifecycle. - `downloadUrl` (`string | null`, required, uri, example https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...) — A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed. - `createdAt` (`string`, required, date-time) — When the report run was requested. - `completedAt` (`string | null`, required, date-time) — When the report run finished generating. Null while it is still in progress. ## [EventEnvelope](/api-reference/models#models/EventEnvelope) The common wrapper around every webhook delivery. Each webhook POST body contains this envelope: a stable event identifier for deduplication, the event type to dispatch on, when the change happened, and the event-specific payload in `data`. Type: `object` - `eventId` (`string`, required, uuid, example b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab) — Unique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency. - `type` (`string`, required, example subscription.created) — Event type identifier (dot namespaced, e.g. subscription.created). - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `apiRevision` (`string`, required, example 2026-08-21.auk) — The API revision that this payload is in. A delivery carries no API key, so the revision comes from the webhook setting of your account and not from a request. Admin > Advanced > Webhooks in the portal shows it and moves it. - `data` (`any`, required) — Event-specific payload; structure depends on event type.