# Seamless Developer Portal — API reference > Every endpoint, webhook and schema in the Seamless OS API at full depth, in the order the reference navigation lists them. Generated from https://docs.telnesstech.com/bundled_openapi.json, which is the better source when you want exact schemas or code generation. The prose documentation is at https://docs.telnesstech.com/llms-full-guides.txt. ## Endpoints ### Auth Canonical URL: https://docs.telnesstech.com/api-reference/auth #### [POST /auth/email/start](/api-reference/auth#tag/auth/POST/auth/email/start) Start email login Initiates an email-based login flow by sending a verification code to the provided email address. The response includes a nonce that must be used when verifying the login, along with timing information for the verification code. This endpoint always returns 202 Accepted to prevent email enumeration attacks. Authentication: Public ##### Request body (required) Type: `object` - `email` (`string`, required, email, example john.doe@example.com) — The email address to send the verification code to. ##### Responses ###### 202 Login flow initiated. A verification code has been sent to the email address if it exists in the system. Type: [StartEmailLoginResponse](/api-reference/models.md#models/StartEmailLoginResponse) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/auth/email/start \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "email": "john.doe@example.com" }' ``` #### [POST /auth/email/verify](/api-reference/auth#tag/auth/POST/auth/email/verify) Verify email login Verifies an email login by validating the verification code sent to the email address. On success, returns an OAuth2-compatible token response with: - `accessToken`: JWT token for authenticating subsequent API requests - `tokenType`: Always "Bearer" - `expiresIn`: Token lifetime in seconds - `userId`: The authenticated user's identifier Use the access token in the Authorization header: `Authorization: Bearer {accessToken}` Authentication: Public ##### Request body (required) 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. ##### Responses ###### 200 Login verified successfully. Returns access token for API authentication. Type: [TokenResponse](/api-reference/models.md#models/TokenResponse) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/auth/email/verify \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "email": "john.doe@example.com", "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "code": "123456" }' ``` ### Customers Canonical URL: https://docs.telnesstech.com/api-reference/customers #### [GET /customers](/api-reference/customers#tag/customers/GET/customers) List customers List all customers. Will return all customers the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `filter` (`string`, optional) — A free text search string to filter customers. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of customers. Type: `object` - `items` (`array of Customer`, required) - `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. - `street1` (`string`, required, example 500 S Main St) — 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 to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `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. - `street1` (`string`, required, example 500 S Main St) — 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) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/customers \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /customers](/api-reference/customers#tag/customers/POST/customers) Create customer Create a new customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 201 Customer created successfully. Type: [Customer](/api-reference/models.md#models/Customer) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/customers \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "customerType": "BUSINESS", "name": "Acme Corp", "referenceId": "crm-customer-12345", "preferredLocale": "en-US", "contact": { "email": "john.doe@example.com", "msisdn": "+15551234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@example.com", "currency": "USD" }, "userIds": [ "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" ], "contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street1": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } } }' ``` #### [GET /customers/{customerId}](/api-reference/customers#tag/customers/GET/customers/{customerId}) Get customer Get a customer by ID or referenceId. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 Customer details. Type: [Customer](/api-reference/models.md#models/Customer) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [PUT /customers/{customerId}](/api-reference/customers#tag/customers/PUT/customers/{customerId}) Update customer Update an existing customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 200 Customer updated successfully. Type: [Customer](/api-reference/models.md#models/Customer) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "contact": { "email": "newemail@example.com", "msisdn": "+15559876543" } }' ``` #### [DELETE /customers/{customerId}/users](/api-reference/customers#tag/customers/DELETE/customers/{customerId}/users) Remove user from customer Remove a user from a customer. The user keeps their account, so they can still be added to another customer later, but loses the roles and permissions this customer granted them. A customer's contact person cannot be removed — assign another contact person first. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Query parameters - `userId` (`string`, required) — The unique identifier of the user to remove from the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 200 User removed from customer successfully. Type: [Customer](/api-reference/models.md#models/Customer) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users?userId=USER_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /customers/{customerId}/product-catalog](/api-reference/customers#tag/customers/GET/customers/{customerId}/product-catalog) Get customer product catalog Get the customer's product catalog, this is a combination of the default product catalog configured in the system and other product catalogs assigned to the customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer to fetch the product catalog for. 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. ##### Responses ###### 200 Customer product catalog. Type: `object` - `productOfferingGroups` (`array of ProductOfferingGroup`, optional) — The product groups in this catalog. - `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, 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 - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `productOfferings` (`array of ProductOffering`, optional) — The product offerings available in this catalog. - `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. - `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, 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 - `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, 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 - `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`). - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/product-catalog \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Inventory Canonical URL: https://docs.telnesstech.com/api-reference/inventory #### [POST /inventory/lease-numbers](/api-reference/inventory#tag/inventory/POST/inventory/lease-numbers) Lease phone numbers Reserve phone numbers from inventory for use in orders. This allows customers to choose specific numbers before completing their order. **Availability**: This feature is part of our premium number selection offering and may not be available for all product offerings. Check the response for availability information. **Usage Flow**: 1. Lease numbers to get a lease token 2. Use the lease token and chosen msisdn in subscription line items 3. Numbers are automatically released if not used before expiry **Important**: Leased numbers expire after a short time (typically 1 hour) to prevent inventory hoarding. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. ##### Responses ###### 200 Numbers leased successfully. Type: [NumberLeaseResult](/api-reference/models.md#models/NumberLeaseResult) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/inventory/lease-numbers \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "types": [ "CELL" ], "count": 2 }' ``` #### [GET /inventory/sims/{iccid}](/api-reference/inventory#tag/inventory/GET/inventory/sims/{iccid}) Get SIM details Retrieve details of a SIM card from inventory by its ICCID. For eSIM cards linked to a subscription, the response includes live installation status from the network operator, showing whether the profile has been downloaded, installed, or enabled on a device. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `iccid` (`string`, required) — The ICCID of the SIM card to retrieve. ##### Responses ###### 200 SIM details retrieved successfully. Type: [InventorySim](/api-reference/models.md#models/InventorySim) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/inventory/sims/8946200508271016579 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Invoices Canonical URL: https://docs.telnesstech.com/api-reference/invoices #### [GET /invoices](/api-reference/invoices#tag/invoices/GET/invoices) List invoices Retrieve a paginated list of invoices with optional filtering by status, customer, or date range. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. - `customerId` (`array of string`, optional) — Filter invoices by customer IDs - `status` (`array of InvoiceStatus`, optional) — Filter invoices by status - `fromDate` (`string`, optional, date) — Filter invoices created from this date - `toDate` (`string`, optional, date) — Filter invoices created up to this date - `dueDateFrom` (`string`, optional, date) — Filter invoices with due date from this date - `dueDateTo` (`string`, optional, date) — Filter invoices with due date up to this date ##### Responses ###### 200 Invoices retrieved successfully Type: `object` - `items` (`array of InvoiceListItem`, required) - `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 is for. - `invoiceNumber` (`string`, required, example INV-2024-001) — Human-readable invoice number. - `status` (`enum`, required, one of DRAFT, SENT, PAID, VOID, OVERDUE, example SENT) — Current status of the invoice. — Current stage of the invoice lifecycle. - DRAFT: Being prepared; not yet visible to the customer. - SENT: Delivered to the customer and awaiting payment. - PAID: Payment has been received. - VOID: Canceled and no longer collectible. - OVERDUE: Past its due date without payment. - `dueDate` (`string`, required, date, example 2024-02-15) — When payment is due. - `subtotalAmountMinor` (`integer`, optional, int64, example 2999) — Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD). - `totalAmountMinor` (`integer`, optional, int64, example 2989) — Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units. - `currency` (`string`, optional, example USD) — The ISO 4217 currency code for all invoice amounts (e.g., "USD"). - `sentAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the invoice was sent to the customer (if status is sent or later). - `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the invoice was paid (if status is paid). - `voidedAt` (`string`, optional, date-time, example 2024-02-05T09:00:00Z) — When the invoice was voided (if status is void). - `invoiceUrl` (`string`, optional, uri, example https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d) — Hosted URL where customer can view the invoice. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/invoices \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /invoices/{invoiceId}](/api-reference/invoices#tag/invoices/GET/invoices/{invoiceId}) Get invoice Retrieve details of a specific invoice by its identifier, including status, due date, and payment information. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `invoiceId` (`string`, required) — The unique identifier of the invoice to retrieve. ##### Responses ###### 200 Invoice retrieved successfully Type: [Invoice](/api-reference/models.md#models/Invoice) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /invoices/{invoiceId}/mark-paid](/api-reference/invoices#tag/invoices/POST/invoices/{invoiceId}/mark-paid) Mark invoice as paid Mark an invoice as paid when you manage your own payment processing. Use this when you handle payment collection while Telness manages invoice generation and taxation. Only available for invoices in `SENT` or `OVERDUE` status. Triggers subscription renewals and prevents service cancellation. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `invoiceId` (`string`, required) — The unique identifier of the invoice to mark as paid. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (optional) 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) ##### Responses ###### 200 Invoice successfully marked as paid. Type: [Invoice](/api-reference/models.md#models/Invoice) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "paidAt": "2024-02-10T14:30:00Z", "metadata": { "propertyName": "string" } }' ``` ### Licenses Canonical URL: https://docs.telnesstech.com/api-reference/licenses #### [GET /licenses](/api-reference/licenses#tag/licenses/GET/licenses) List licenses List all licenses. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `customerId` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `type` (`array of LicenseType`, optional) — The type of license to filter by. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of licenses. Type: `object` - `items` (`array of License`, required) - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /licenses](/api-reference/licenses#tag/licenses/POST/licenses) Create license Create a new license Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `productOfferingId` (`string`, required, example a7b8c9d0-e1f2-3456-7890-bcdef0123456) — The unique identifier for the product offering to subscribe to. This controls what type of license is being created. - `customerId` (`string`, required, uuid, example b8c9d0e1-f2a3-4567-8901-cdef01234567) — The unique identifier for the existing customer who will own this license. - `licenseType` (`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. - `assignedTo` (`one of`, required) — Assignment reference for a license, indicating what entity the license is assigned to. This is a simplified version for list operations - use EmbeddedAssignedTo for detailed views. - `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 should be activated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 201 License created successfully. Type: [License](/api-reference/models.md#models/License) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "productOfferingId": "a7b8c9d0-e1f2-3456-7890-bcdef0123456", "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567", "licenseType": "PBX_USER_LEVEL", "assignedTo": { "type": "SUBSCRIPTION", "subscriptionId": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "scheduleActivationAt": "2024-01-20" }' ``` #### [GET /licenses/{licenseId}](/api-reference/licenses#tag/licenses/GET/licenses/{licenseId}) Get license Retrieve detailed information about a specific license using its unique identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `licenseId` (`string`, required) — The unique identifier of the license. ##### Responses ###### 200 A license object. Type: [License](/api-reference/models.md#models/License) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses/LICENSE_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [PUT /licenses/{licenseId}/product-offering-change](/api-reference/licenses#tag/licenses/PUT/licenses/{licenseId}/product-offering-change) Change license product offering Change the product offering of a license (upgrade or downgrade). To get a list of what product offerings the license can be changed to and when, get change options for the license. When the change takes effect is dictated by what product offering is chosen, which in turn depends on the license terms and billing cycle. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `licenseId` (`string`, required) — The unique identifier of the license. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the 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) ##### Responses ###### 200 Product offering change scheduled. Type: [License](/api-reference/models.md#models/License) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses/LICENSE_ID/product-offering-change \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "scheduledAt": "2024-02-01", "metadata": { "propertyName": "string" } }' ``` #### [GET /licenses/{licenseId}/product-offering-options](/api-reference/licenses#tag/licenses/GET/licenses/{licenseId}/product-offering-options) Get product offering options for license Get all available product offerings a license can be changed to and when the change can take effect. When the license can be changed typically depends on the license terms, billing cycle, and current product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `licenseId` (`string`, required) — The unique identifier of the license. ##### Responses ###### 200 Available change options. Type: `object` - `items` (`array of ProductOfferingOption`, required) - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses/LICENSE_ID/product-offering-options \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /licenses/{licenseId}/cancel](/api-reference/licenses#tag/licenses/POST/licenses/{licenseId}/cancel) Cancel license Cancel a license. This endpoint allows cancelling a license with an optional scheduled date. The cancellation will take effect according to the specified schedule or immediately if no schedule is provided. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `licenseId` (`string`, required) — The unique identifier of the license. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (optional) 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) ##### Responses ###### 200 License cancellation scheduled successfully. Type: [License](/api-reference/models.md#models/License) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/licenses/LICENSE_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "scheduledAt": "2024-03-01", "metadata": { "propertyName": "string" } }' ``` ### Orders Canonical URL: https://docs.telnesstech.com/api-reference/orders #### [POST /orders](/api-reference/orders#tag/orders/POST/orders) Create order Create a new order with initial configuration. Orders can be created with minimal information and progressively configured. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 `promo_code_not_redeemable` 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) ##### Responses ###### 201 Order created successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "customerType": "BUSINESS", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street1": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com" } } ], "promoCode": "SUMMER2023", "metadata": { "source": "partner-storefront" } }' ``` #### [GET /orders](/api-reference/orders#tag/orders/GET/orders) List orders List orders with optional filtering and pagination. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. - `state` (`enum`, optional, one of PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED) — Filter by order state — 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 - `userId` (`string`, optional) — Filter by user ID - `customerId` (`string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `expiresAfter` (`string`, optional, date-time) — Filter orders expiring after this date - `expiresBefore` (`string`, optional, date-time) — Filter orders expiring before this date ##### Responses ###### 200 Orders retrieved successfully Type: `object` - `items` (`array of OrderListItem`, required) - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Final order total including all taxes and fees, in major currency units. - `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. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /orders/{orderId}](/api-reference/orders#tag/orders/GET/orders/{orderId}) Get order Retrieve a specific order by ID with all line items and current status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Responses ###### 200 Order retrieved successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [PUT /orders/{orderId}](/api-reference/orders#tag/orders/PUT/orders/{orderId}) Update order Update order details (excluding line items). Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Request body (required) 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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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 `promo_code_not_redeemable` 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) ##### Responses ###### 200 Order updated successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "user": { "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479" }, "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "billing": { "name": "John Doe", "email": "billing@example.com", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" }, "instructions": "Leave at front door" }, "consents": { "termsOfService": "true", "marketing": "true" }, "promoCode": "STUDENT2024", "metadata": { "propertyName": "string" } }' ``` #### [POST /orders/{orderId}/line-items](/api-reference/orders#tag/orders/POST/orders/{orderId}/line-items) Add line item Add a new line item to an order. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. ##### Responses ###### 201 Line item added successfully Type: [OrderLineItem](/api-reference/models.md#models/OrderLineItem) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "lineItem": { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "msisdn": "+15551234567", "leaseToken": "lease_8f3b1c2d4e5f6789", "tempNumber": true, "portingRequested": true, "porting": { "details": { "accountNumber": "987654321", "passcode": "123456", "firstName": "John", "lastName": "Doe", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } } }, "extensions": { "propertyName": "string" }, "display": "John Doe - Work phone", "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "sim": { "esim": true, "imei": "356938035643809", "iccid": "8931440400000000000" }, "scheduleActivationAt": "2024-02-01", "activateOnDemand": true, "metadata": { "propertyName": "string" } } }' ``` #### [PUT /orders/{orderId}/line-items/{lineItemId}](/api-reference/orders#tag/orders/PUT/orders/{orderId}/line-items/{lineItemId}) Update line item Update a line item configuration. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order - `lineItemId` (`string`, required) — The unique identifier of the line item ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. ##### Responses ###### 200 Line item updated successfully Type: [OrderLineItem](/api-reference/models.md#models/OrderLineItem) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "lineItem": { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "msisdn": "+15551234567", "leaseToken": "lease_8f3b1c2d4e5f6789", "tempNumber": true, "portingRequested": true, "porting": { "details": { "accountNumber": "987654321", "passcode": "123456", "firstName": "John", "lastName": "Doe", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } } }, "extensions": { "propertyName": "string" }, "display": "John Doe - Work phone", "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "sim": { "esim": true, "imei": "356938035643809", "iccid": "8931440400000000000" }, "scheduleActivationAt": "2024-02-01", "activateOnDemand": true, "metadata": { "propertyName": "string" } } }' ``` #### [DELETE /orders/{orderId}/line-items/{lineItemId}](/api-reference/orders#tag/orders/DELETE/orders/{orderId}/line-items/{lineItemId}) Remove line item Remove a line item from an order. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order - `lineItemId` (`string`, required) — The unique identifier of the line item ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 204 Line item removed successfully ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /orders/{orderId}/calculate-price](/api-reference/orders#tag/orders/POST/orders/{orderId}/calculate-price) Calculate order price Deprecated. The order's pricing is recalculated on every change and returned as `pricing` on the order itself; read it from `GET /orders/{orderId}` instead. This endpoint returns that same stored pricing. Invalid orders cannot be priced. Fetch the order to see validation errors. Deprecated. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 200 Price calculation completed successfully Type: `object` - `pricing` (`object`, required) — Detailed pricing information for an order including taxes and discounts. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `initialInvoiceAmountMinor` (`integer`, optional, int64, example 1450) — Amount for this line item on the first invoice when different from recurring, in minor currency units. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/calculate-price \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /orders/{orderId}/submit](/api-reference/orders#tag/orders/POST/orders/{orderId}/submit) Submit order Submit an order for fulfillment. Requires payment, signing, or card capture, depending on the setup. Only orders in the PENDING state can be submitted. An order paying through a payment session or payment link is in PENDING_PAYMENT and is submitted automatically once the payment succeeds — poll the order or subscribe to the order.statusChanged webhook instead of calling this endpoint. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 200 Order submitted successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/submit \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901" }' ``` #### [POST /orders/{orderId}/cancel](/api-reference/orders#tag/orders/POST/orders/{orderId}/cancel) Cancel order Cancel an order before it has been submitted. Only orders in PENDING status can be canceled. This prevents the order from being submitted and cleans up any reserved resources. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Request body (optional) Type: `object` - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Order canceled successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "metadata": { "propertyName": "string" } }' ``` #### [POST /orders/{orderId}/approve](/api-reference/orders#tag/orders/POST/orders/{orderId}/approve) Approve order Approve an order that requires admin or manager approval. Only orders in PENDING_APPROVAL status can be approved. The approving user must have the appropriate role for the approval type required by the order. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ##### Request body (optional) Type: `object` - `comment` (`string`, optional, max length 1000, example Approved after reviewing customer credit check) — Optional comment explaining the approval decision. ##### Responses ###### 200 Order approved successfully Type: [Order](/api-reference/models.md#models/Order) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/approve \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "comment": "Approved after reviewing customer credit check" }' ``` ### Payment Intents Canonical URL: https://docs.telnesstech.com/api-reference/payment-intents #### [GET /payment-intents](/api-reference/payment-intents#tag/payment-intents/GET/payment-intents) List payment intents Retrieve a paginated list of payment intents with optional filtering by status, customer, or date range. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. - `customerId` (`array of string`, optional) — Filter payment intents by customer IDs - `status` (`array of PaymentIntentStatus`, optional) — Filter payment intents by status ##### Responses ###### 200 Payment intents retrieved successfully Type: `object` - `items` (`array of PaymentIntentListItem`, required) - `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 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. - 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. - `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. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-intents \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /payment-intents/{paymentIntentId}](/api-reference/payment-intents#tag/payment-intents/GET/payment-intents/{paymentIntentId}) Get payment intent Get a payment intent by ID, including its charge attempts, refunds, and line items. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentIntentId` (`string`, required) — The unique identifier of the payment intent to retrieve. ##### Responses ###### 200 Payment intent retrieved successfully Type: [PaymentIntent](/api-reference/models.md#models/PaymentIntent) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-intents/64870b5c-fb61-4c9a-955a-e148e0826c20 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Payment Links Canonical URL: https://docs.telnesstech.com/api-reference/payment-links #### [GET /payment-links](/api-reference/payment-links#tag/payment-links/GET/payment-links) List payment links Get a list of payment links. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `status` (`array of PaymentLinkStatus`, optional) — Filter by payment link status. - `customerId` (`string`, optional) — Filter by customer ID. - `orderId` (`string`, optional) — Filter by order ID. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 List of payment links. Type: `object` - `items` (`array of PaymentLink`, required) - `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) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /payment-links](/api-reference/payment-links#tag/payment-links/POST/payment-links) Create payment link Create a new payment link that can be shared with customers to collect payments. Payment links provide a hosted checkout experience without requiring integration with payment widgets or handling sensitive payment data directly. The order must be complete and ready for submission — an order that would fail submission validation is rejected before any payment is collected. Once the payment succeeds, the order is submitted automatically. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 201 Payment link created successfully. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "description": "Pay for your mobile subscription order", "savePaymentProfile": true, "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout" }' ``` #### [GET /payment-links/{paymentLinkId}](/api-reference/payment-links#tag/payment-links/GET/payment-links/{paymentLinkId}) Get payment link Retrieve details of a specific payment link. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentLinkId` (`string`, required) — The unique identifier for the payment link. ##### Responses ###### 200 Payment link details. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /payment-links/{paymentLinkId}/cancel](/api-reference/payment-links#tag/payment-links/POST/payment-links/{paymentLinkId}/cancel) Cancel payment link Cancel an active payment link, preventing further payment attempts through the link. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentLinkId` (`string`, required) — The unique identifier for the payment link. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 200 Payment link details. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Payment Profile Sessions Canonical URL: https://docs.telnesstech.com/api-reference/payment-profile-sessions #### [POST /payment-profiles/sessions](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/POST/payment-profiles/sessions) Create payment profile session Create a new payment profile session to set up and save a payment method for future use. Used for zero-cost orders where payment collection isn't needed but payment method setup is required. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 201 Payment profile session created successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "9f8e7d6c-5b4a-3210-9876-543210987654", "paymentProvider": "STRIPE", "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout", "setAsDefaultPaymentProfile": false, "metadata": { "propertyName": "string" } }' ``` #### [GET /payment-profiles/sessions/{paymentProfileSessionId}](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/GET/payment-profiles/sessions/{paymentProfileSessionId}) Get payment profile session Retrieve details of a specific payment profile session by its identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentProfileSessionId` (`string`, required) — The unique identifier of the payment profile session to retrieve. ##### Responses ###### 200 Payment profile session retrieved successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions/b4c5d6e7-f8a9-0123-4567-234567890123 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /payment-profiles/sessions/{paymentProfileSessionId}/cancel](/api-reference/payment-profile-sessions#tag/payment-profile-sessions/POST/payment-profiles/sessions/{paymentProfileSessionId}/cancel) Cancel payment profile session Cancel an active payment profile session, preventing further setup attempts. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentProfileSessionId` (`string`, required) — The unique identifier of the payment profile session to cancel. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (optional) 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) ##### Responses ###### 200 Payment profile session canceled successfully Type: [PaymentProfileSession](/api-reference/models.md#models/PaymentProfileSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/sessions/c5d6e7f8-a9b0-1234-5678-345678901234/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "reason": "Customer decided not to save payment method", "metadata": { "cancelled_by": "customer_service", "ticket_id": "SUPP-12345" } }' ``` ### Payment Profiles Canonical URL: https://docs.telnesstech.com/api-reference/payment-profiles #### [GET /payment-profiles](/api-reference/payment-profiles#tag/payment-profiles/GET/payment-profiles) List payment profiles for customer List saved payment profiles for the customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `customerId` (`string`, required) — Filter profiles for a specific customer. ##### Responses ###### 200 Payment profiles retrieved successfully. Type: `object` - `items` (`array of EmbeddedPaymentProfile`, required) — List of saved payment profiles. - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/payment-profiles?customerId=d0e1f2a3-b4c5-6789-0123-ef0123456789' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /payment-profiles/{paymentProfileId}](/api-reference/payment-profiles#tag/payment-profiles/GET/payment-profiles/{paymentProfileId}) Get payment profile Retrieve details of a specific saved payment method by its identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentProfileId` (`string`, required) — The unique identifier of the payment profile to retrieve. ##### Responses ###### 200 Payment profile retrieved successfully Type: [PaymentProfile](/api-reference/models.md#models/PaymentProfile) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/e1f2a3b4-c5d6-7890-1234-f01234567890 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [DELETE /payment-profiles/{paymentProfileId}](/api-reference/payment-profiles#tag/payment-profiles/DELETE/payment-profiles/{paymentProfileId}) Delete payment profile Remove a saved payment method permanently. This action cannot be undone and will prevent future use of this payment profile. If a payment profile is set as default for a customer, it must first be changed before deletion. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentProfileId` (`string`, required) — The unique identifier of the payment profile to delete. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 204 Payment profile deleted successfully ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-profiles/e1f2a3b4-c5d6-7890-1234-f01234567890 \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Payment Sessions Canonical URL: https://docs.telnesstech.com/api-reference/payment-sessions #### [POST /payment-sessions](/api-reference/payment-sessions#tag/payment-sessions/POST/payment-sessions) Create payment session Create a new payment session to collect payment information for an order. For orders with a positive total, this initiates payment collection. For zero-total orders, consider creating a payment profile session instead. The order must be complete and ready for submission — an order that would fail submission validation is rejected before any payment is collected. Once the payment succeeds, the order is submitted automatically. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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 create a hosted checkout session. Currently all payment sessions use the hosted checkout flow, so a hosted payment page URL is always returned regardless of this value. - `returnUrl` (`string`, required, example https://example.com/order/confirmation) — The URL the customer is redirected to after completing payment on the hosted page. 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. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 201 Payment session created successfully Type: [PaymentSession](/api-reference/models.md#models/PaymentSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-sessions \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "paymentProvider": "STRIPE", "savePaymentProfile": true, "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout", "metadata": { "source": "web-checkout" } }' ``` #### [GET /payment-sessions/{paymentSessionId}](/api-reference/payment-sessions#tag/payment-sessions/GET/payment-sessions/{paymentSessionId}) Get payment session Retrieve details of a specific payment session by its identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentSessionId` (`string`, required) — The unique identifier of the payment session to retrieve. ##### Responses ###### 200 Payment session retrieved successfully Type: [PaymentSession](/api-reference/models.md#models/PaymentSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /payment-sessions/{paymentSessionId}/cancel](/api-reference/payment-sessions#tag/payment-sessions/POST/payment-sessions/{paymentSessionId}/cancel) Cancel payment session Cancel an active payment session, preventing further payment attempts. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `paymentSessionId` (`string`, required) — The unique identifier of the payment session to cancel. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (optional) 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) ##### Responses ###### 200 Payment session canceled successfully Type: [PaymentSession](/api-reference/models.md#models/PaymentSession) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "reason": "Customer changed their mind", "metadata": { "cancelled_by": "customer_service", "ticket_id": "SUPP-12345" } }' ``` ### Porting Canonical URL: https://docs.telnesstech.com/api-reference/porting #### [GET /subscriptions/{subscriptionId}/in-porting](/api-reference/porting#tag/porting/GET/subscriptions/{subscriptionId}/in-porting) Get subscription in-porting Retrieve the current porting information for a subscription that is in the process of porting in a number. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 Porting information retrieved successfully. Type: [Porting](/api-reference/models.md#models/Porting) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/in-porting](/api-reference/porting#tag/porting/POST/subscriptions/{subscriptionId}/in-porting) Update subscription porting details Update the porting details for a subscription that is in the process of porting in a number. This endpoint allows you to modify porting information while the port is still pending or in progress. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. ##### Responses ###### 200 Porting details updated successfully. Type: `object` - `subscription` (`object`, optional) — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) - `portingInfo` (`object`, optional) — Updated porting information and status. - `portingId` (`string`, optional) — The unique identifier for this porting request. - `status` (`enum`, optional, one of pending, in_progress, scheduled, completed, failed) — Current status of the porting process. - `estimatedCompletion` (`string`, optional, date-time) — Estimated completion time for the port. - `nextSteps` (`array of string`, optional) — Next steps required to complete the porting process. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "details": { "identity": "199001011234" } }' ``` ### Product Catalogs Canonical URL: https://docs.telnesstech.com/api-reference/product-catalogs #### [GET /product-catalogs](/api-reference/product-catalogs#tag/product-catalogs/GET/product-catalogs) List product catalogs List all product catalogs with optional text search filtering and pagination. Product catalogs define curated sets of product offerings for specific contexts such as customer segments, regions, or sales channels. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `filter` (`string`, optional) — Filter by catalog name or ID prefix. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of product catalogs. Type: `object` - `items` (`array of ProductCatalogListItem`, required) - `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. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/product-catalogs \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Product Discounts Canonical URL: https://docs.telnesstech.com/api-reference/product-discounts #### [GET /discounts/promotions/promo-code/{promoCode}](/api-reference/product-discounts#tag/product-discounts/GET/discounts/promotions/promo-code/{promoCode}) Get promotion by code Look up a promotion by its promotional code to check availability and details. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `promoCode` (`string`, required) — The promotional code to look up. ##### Responses ###### 200 Promotion details including associated discount information. Type: [Promotion](/api-reference/models.md#models/Promotion) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/discounts/promotions/promo-code/SUMMER25 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Product Offerings Canonical URL: https://docs.telnesstech.com/api-reference/product-offerings #### [GET /product-offerings](/api-reference/product-offerings#tag/product-offerings/GET/product-offerings) List product offerings List all product offerings available to the customer. Returns product offerings based on the customer type and access permissions. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `types` (`array of ProductType`, optional) — Filter by product offering types. - `categories` (`array of ProductCategory`, optional) — Filter by product offering categories. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Filter by customer type. — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `productCatalogId` (`string`, optional) — Filter by product catalog. Returns only product offerings that belong to the specified catalog. When combined with other filters, all filters are applied together. - `includeArchived` (`boolean`, optional, default false) — Whether to include archived product offerings. - `countries` (`array of string`, optional) — Filter by country coverage using ISO 3166-1 alpha-3 codes. Returns offerings that provide coverage in any of the specified countries. This includes offerings that have the country explicitly listed or are part of a region that includes the country. - `regions` (`array of string`, optional) — Filter by region coverage. Returns offerings that provide coverage in any of the specified regions. Retrieve the available region identifiers from the List Travel eSIM countries endpoint. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of product offerings. Type: `object` - `items` (`array of ProductOffering`, required) - `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. - `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, 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 - `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, 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 - `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`). - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/product-offerings?customerType=CONSUMER' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /product-offerings/{productOfferingId}](/api-reference/product-offerings#tag/product-offerings/GET/product-offerings/{productOfferingId}) Get product offering Get a product offering by ID. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `productOfferingId` (`string`, required) — The unique identifier of the product offering. ##### Responses ###### 200 Product offering details. Type: [ProductOffering](/api-reference/models.md#models/ProductOffering) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/product-offerings/PRODUCT_OFFERING_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /product-offerings/countries](/api-reference/product-offerings#tag/product-offerings/GET/product-offerings/countries) List Travel eSIM countries List all countries and regions available across travel eSIM product offerings. Returns a deduplicated list of countries with their names and ISO codes, plus regions that appear on offerings with their constituent country codes. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Filter by customer type. — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. ##### Responses ###### 200 A list of countries and regions available across product offerings. Type: `object` - `countries` (`array of object`, required) - `code` (`string`, required, example USA) — ISO 3166-1 alpha-3 country code. - `name` (`string`, required, example United States) — The English name of the country. - `regions` (`array of object`, required) - `region` (`string`, required, example EUROPE) — The region identifier. - `countries` (`array of string`, required, example ["SWE","DEU","FRA"]) — ISO 3166-1 alpha-3 country codes available within this region. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/product-offerings/countries?customerType=CONSUMER' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Reports Canonical URL: https://docs.telnesstech.com/api-reference/reports #### [GET /reports](/api-reference/reports#tag/reports/GET/reports) List reports List platform-generated report runs for a given report key, newest first. Only report runs created within the last 30 days are returned. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `reportKey` (`string`, required) — The key identifying the report to list runs for. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of report runs. Type: `object` - `items` (`array of ReportRun`, required) - `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. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/reports?reportKey=REPORT_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /reports/{reportRunId}](/api-reference/reports#tag/reports/GET/reports/{reportRunId}) Get report Retrieve a generated report by its identifier. Once the report has finished generating, the response includes a time-limited link to download the file directly. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `reportRunId` (`string`, required, uuid) — The identifier of the report run. ##### Responses ###### 200 A report run object. Type: [ReportRun](/api-reference/models.md#models/ReportRun) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6 \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Subscribers Canonical URL: https://docs.telnesstech.com/api-reference/subscribers #### [GET /subscribers](/api-reference/subscribers#tag/subscribers/GET/subscribers) List subscribers List all subscribers. Will return all subscribers the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `customerIds` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `subscriptionIds` (`array of string`, optional) — The unique identifier of the subscription to filter by. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of subscribers. Type: `object` - `items` (`array of SubscriberListItem`, required) - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscribers \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /subscribers/{subscriberId}](/api-reference/subscribers#tag/subscribers/GET/subscribers/{subscriberId}) Get subscriber Retrieve detailed information about a specific subscriber using its unique identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriberId` (`string`, required) — The unique identifier of the subscriber. ##### Responses ###### 200 A subscriber object. Type: [Subscriber](/api-reference/models.md#models/Subscriber) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscribers/SUBSCRIBER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [PUT /subscribers/{subscriberId}](/api-reference/subscribers#tag/subscribers/PUT/subscribers/{subscriberId}) Update subscriber Update the details of an existing subscriber. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriberId` (`string`, required) — The unique identifier of the subscriber. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 200 Subscriber updated successfully. Type: [Subscriber](/api-reference/models.md#models/Subscriber) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscribers/SUBSCRIBER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "John Doe", "email": "john.doe@example.com", "contactNumber": "+15551234567", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" }, "metadata": { "propertyName": "string" } }' ``` ### Subscription Addons Canonical URL: https://docs.telnesstech.com/api-reference/subscription-addons #### [GET /subscriptions/{subscriptionId}/addons](/api-reference/subscription-addons#tag/subscription-addons/GET/subscriptions/{subscriptionId}/addons) List active add-ons for subscription Get all active and pending add-ons for a subscription. This endpoint returns only add-ons that are currently attached to the subscription, including their status and scheduling information. Use /addon-options to query available add-ons. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Query parameters - `status` (`array of SubscriptionAddonStatus`, optional) — Filter add-ons by status. ##### Responses ###### 200 Active add-ons for the subscription. Type: `object` - `items` (`array of SubscriptionAddon`, required) - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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, 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 - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, required) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/addons](/api-reference/subscription-addons#tag/subscription-addons/POST/subscriptions/{subscriptionId}/addons) Add subscription add-on Add an add-on to a subscription. This endpoint includes adding an add-on to a subscription. The add-on can be scheduled to be activated immediately or at a future date. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the 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) ##### Responses ###### 201 Add-on added successfully. Type: [SubscriptionAddon](/api-reference/models.md#models/SubscriptionAddon) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "scheduledAt": "2024-03-01", "metadata": { "propertyName": "string" } }' ``` #### [POST /subscriptions/{subscriptionId}/addons/cancel](/api-reference/subscription-addons#tag/subscription-addons/POST/subscriptions/{subscriptionId}/addons/cancel) Cancel subscription add-on Cancel an add-on on a subscription. This endpoint allows cancelling active add-ons on a subscription. The add-on will be canceled according to the specified schedule or immediately if no schedule is provided. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 200 Add-on cancellation scheduled successfully. Type: [SubscriptionAddon](/api-reference/models.md#models/SubscriptionAddon) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "scheduledAt": "2024-03-01", "reason": "No longer needed", "metadata": { "propertyName": "string" } }' ``` #### [PUT /subscriptions/{subscriptionId}/addons/product-offering-change](/api-reference/subscription-addons#tag/subscription-addons/PUT/subscriptions/{subscriptionId}/addons/product-offering-change) Change subscription add-on product offering Change an existing add-on to a different product offering (upgrade or downgrade). This endpoint allows you to change an existing add-on attached to a subscription to a different add-on product offering. The change can be scheduled for immediate or future execution. When the change takes effect depends on the new product offering chosen, billing cycle, and the preferred schedule date provided in the request. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 200 Add-on change scheduled successfully. Type: [SubscriptionAddon](/api-reference/models.md#models/SubscriptionAddon) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-change \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "productOfferingId": "addon-data-5gb", "scheduledAt": "2024-02-01", "reason": "Customer upgrade request", "metadata": { "propertyName": "string" } }' ``` #### [GET /subscriptions/{subscriptionId}/addons/product-offering-options](/api-reference/subscription-addons#tag/subscription-addons/GET/subscriptions/{subscriptionId}/addons/product-offering-options) Get change options for subscription add-on Get all available product offerings an existing add-on can be changed to and when the change can take effect. When the add-on can be changed typically depends on the network setup, billing cycle, and current add-on product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Query parameters - `currentProductOfferingId` (`string`, required) — The current add-on product offering to get change options for. ##### Responses ###### 200 Available change options for the add-on. Type: `object` - `items` (`array of ProductOfferingOption`, required) - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/addons/product-offering-options?currentProductOfferingId=CURRENT_PRODUCT_OFFERING_ID' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Subscription Usage Canonical URL: https://docs.telnesstech.com/api-reference/subscription-usage #### [GET /subscriptions/{subscriptionId}/usage](/api-reference/subscription-usage#tag/subscription-usage/GET/subscriptions/{subscriptionId}/usage) Get subscription usage Retrieve the current period's usage for a subscription. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 Current usage statistics for the subscription. Type: [Usage](/api-reference/models.md#models/Usage) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [GET /subscriptions/usage](/api-reference/subscription-usage#tag/subscription-usage/GET/subscriptions/usage) Get usage for multiple subscriptions Retrieve current usage statistics for multiple subscriptions by providing their IDs. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `subscriptionIds` (`array of string`, required, min items 1, max items 100) — List of subscription IDs to retrieve usage for. ##### Responses ###### 200 Usage statistics for the requested subscriptions. Type: `object` - `items` (`array of object`, required) — Usage information for each requested subscription. - `subscriptionId` (`string`, required, example 123e4567-e89b-12d3-a456-426614174000) — The unique identifier for the subscription. - `usage` (`object`, required) — 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. - `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. - `balance` (`number`, optional, double, deprecated, example 15.5) — Deprecated. Use `balanceMinor` instead. Remaining prepaid amount available for international long distance calls, in major units of the currency given by `currency`. - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl 'https://apiv2.example.com/api/v2/subscriptions/usage?subscriptionIds=SUBSCRIPTION_IDS' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Subscriptions Canonical URL: https://docs.telnesstech.com/api-reference/subscriptions #### [GET /subscriptions](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions) List subscriptions List all subscriptions. Will return all subscriptions the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `customerId` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `status` (`array of SubscriptionStatus`, optional) — The status of the subscription to filter by. - `type` (`array of SubscriptionType`, optional) - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of subscriptions. Type: `object` - `items` (`array of Subscription`, required) - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions) Create subscription Create a new subscription for a customer. **Activation Modes:** 1. **Immediate Activation** - Provide complete activation data in the request - Omit scheduleActivationAt or set to today's date - Subscription activates immediately (network availability permitting) 2. **Scheduled Activation** - Provide complete activation data in the request - Set scheduleActivationAt to a future date - Subscription activates on or after the specified date 3. **Deferred Activation (Shell Subscription)** - Omit activation data from the request - Subscription created in PENDING state - Use the activate endpoint later when activation details are available **Common use cases:** - Standard activation: Customer has all details ready (number choice, SIM type, porting info) - Scheduled activation: Activate on a specific date (e.g., start of billing cycle, go-live date) - Shell subscription: Bulk subscription creation, waiting for SIM delivery, phased onboarding **Note**: This endpoint may be disabled when Seamless OS manages billing. In that configuration, subscriptions are created through the orders endpoint instead. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering to subscribe to. This controls what type of subscription is being created. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — Optional reference ID to assign to the subscription. Must be unique per tenant. Once set, this value can be used in place of the subscriptionId in path parameters and request bodies across the API. - `activation` (`object`, optional) — Everything needed to bring the subscription online in the mobile network: the phone number (a specific number, a leased number, or empty for automatic assignment), the SIM configuration (eSIM or physical SIM), and optional porting details when the subscriber keeps their existing number from another carrier. **When to provide:** - Provide activation details to have the subscription provisioned in the network — immediately, or on the date given in `scheduleActivationAt` - Omit to create a "shell" subscription that stays in PENDING status until you activate it later via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are not yet known - `msisdn` (`string`, optional, example +15551234567) — The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier - `leaseToken` (`string`, optional, example lease_abc123def456) — Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. - `porting` (`object`, optional) — Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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) — Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 201 The created subscription. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "referenceId": "crm-subscription-12345", "activation": { "msisdn": "+15551234567", "leaseToken": "lease_abc123def456", "porting": { "details": { "accountNumber": "987654321", "passcode": "123456", "firstName": "John", "lastName": "Doe", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } } }, "sim": { "esim": true, "iccid": "8931440400000000000" }, "deliveryAddress": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "scheduleActivationAt": "2024-01-15", "extensions": { "propertyName": "string" }, "display": "John'\''s work phone", "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" }, "metadata": { "propertyName": "string" } }, "metadata": { "propertyName": "string" } }' ``` #### [GET /subscriptions/{subscriptionId}](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}) Get subscription Retrieve detailed information about a specific subscription using its unique identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 A subscription object. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/activate](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/activate) Activate subscription Activate a pending subscription by providing the necessary network activation details. Use this endpoint when a subscription was created as a "shell" without activation data. If the subscription is not pending, an error will be returned. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `activation` (`object`, required) — Complete activation configuration required to bring the subscription online in the network. This includes the phone number assignment, SIM card details, and any number porting information. — Configuration and details required to activate a subscription in the telecommunications network. This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services. - `msisdn` (`string`, optional, example +15551234567) — The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier - `leaseToken` (`string`, optional, example lease_abc123def456) — Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. - `porting` (`object`, optional) — Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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) — Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `scheduleActivationAt` (`string`, optional, date, example 2025-01-01) — Date when the subscription should be scheduled for activation. If not provided, activation will be immediate or as soon as possible based on network availability. **Note**: Network availability and porting timelines may affect exact timing. This date is considered a preference, not a guarantee. The actual activation may occur on or after this date. ##### Responses ###### 200 Subscription activation scheduled or completed successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "activation": { "msisdn": "+15551234567", "leaseToken": "lease_abc123def456", "sim": { "esim": true } } }' ``` #### [GET /subscriptions/{subscriptionId}/in-porting](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/in-porting) Get subscription in-porting Retrieve the current porting information for a subscription that is in the process of porting in a number. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 Porting information retrieved successfully. Type: [Porting](/api-reference/models.md#models/Porting) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/in-porting](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/in-porting) Update subscription porting details Update the porting details for a subscription that is in the process of porting in a number. This endpoint allows you to modify porting information while the port is still pending or in progress. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. ##### Responses ###### 200 Porting details updated successfully. Type: `object` - `subscription` (`object`, optional) — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) - `portingInfo` (`object`, optional) — Updated porting information and status. - `portingId` (`string`, optional) — The unique identifier for this porting request. - `status` (`enum`, optional, one of pending, in_progress, scheduled, completed, failed) — Current status of the porting process. - `estimatedCompletion` (`string`, optional, date-time) — Estimated completion time for the port. - `nextSteps` (`array of string`, optional) — Next steps required to complete the porting process. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "details": { "identity": "199001011234" } }' ``` #### [PUT /subscriptions/{subscriptionId}/product-offering-change](/api-reference/subscriptions#tag/subscriptions/PUT/subscriptions/{subscriptionId}/product-offering-change) Change subscription product offering Change the product offering of a subscription (upgrade or downgrade). To get a list of to what and when the subscription can be changed, get change options for the subscription. When the change takes effect is dictated by what product offering is chosen, which in its place depends on the network setup, billing cycle. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Product offering change scheduled. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "scheduledAt": "2024-02-01", "metadata": { "propertyName": "string" } }' ``` #### [GET /subscriptions/{subscriptionId}/product-offering-options](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/product-offering-options) Get change options for subscription Get all available product offerings a subscription can be changed to and when the change can take effect. When the subscription can be changed typically depends on the network setup, billing cycle, and current product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 Available change options. Type: `object` - `items` (`array of ProductOfferingOption`, required) - `productOffering` (`object`, required) — Essential information about a product offering — what is being sold and at what price — without the full catalog details. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details. - `name` (`string`, required, example Mobile Unlimited) — The customer-facing name of the product offering, suitable for display in checkout and account views. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/cancel](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/cancel) Cancel subscription This endpoint allows cancelling a subscription with various timing options: - Next day cancellation - Beginning of next month cancellation - Specific date cancellation Standardized churn reasons help with reporting and analysis. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `cancelAt` (`one of`, required) — When the subscription should be cancelled. - One of: `CancelNextDay` - `nextDay` (`boolean`, required, example true) — Cancel the subscription the next day. - One of: `CancelAtBeginningOfNextMonth` - `nextMonth` (`boolean`, required, example true) — Cancel the subscription at the beginning of next month. - One of: `CancelAtDate` - `date` (`string`, required, date, example 2024-02-01) — Cancel the subscription on a specific date. - `churn` (`enum`, optional, one of BETTER_DEAL_PRICE, NOT_HAPPY_MISSING_FUNCTIONS, NOT_HAPPY_COVERAGE_SLA, NOT_HAPPY_COMPLEX_ADMIN, NOT_HAPPY_SUPPORT_ENGAGEMENT, FRAUD, FRAUD_ATTEMPT, TEST_OR_MARKETING, NO_NEED, WRONG_ORDER, OTHER) — Standardized reason for the cancellation used for reporting and analysis. If OTHER is provided, please also provide a comment. - `comment` (`string`, optional, example Switching to a different provider) — Optional comment about the cancellation. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Subscription cancellation scheduled successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "cancelAt": { "nextDay": true }, "churn": "BETTER_DEAL_PRICE", "comment": "Switching to a different provider", "metadata": { "propertyName": "string" } }' ``` #### [POST /subscriptions/{subscriptionId}/suspend](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/suspend) Suspend subscription Temporarily suspend a subscription. The customer continues to pay but service is disabled. This is typically used for payment issues or fraud prevention. Supports flexible scheduling: - Immediate suspension - Next day suspension - Beginning of next month suspension - Specific date suspension Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Suspend the subscription on a specific date. - `reason` (`string`, optional, example Payment overdue) — Optional reason for the suspension. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Subscription suspension scheduled successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "scheduledAt": "2024-02-01", "reason": "Payment overdue", "metadata": { "propertyName": "string" } }' ``` #### [POST /subscriptions/{subscriptionId}/pause](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/pause) Pause subscription Pause a subscription. The customer stops paying and service is disabled. This is typically used when a customer wants to temporarily stop service. Supports flexible scheduling: - Immediate pause - Next day pause - Beginning of next month pause - Specific date pause Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Subscription pause scheduled successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "scheduledAt": "2024-02-01", "metadata": { "propertyName": "string" } }' ``` #### [POST /subscriptions/{subscriptionId}/restore](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/restore) Restore subscription Restore a suspended, paused, or blocked subscription back to active state. Supports flexible scheduling: - Immediate restore - Next day restoration - Beginning of next month restoration - Specific date restoration Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Restore the subscription on a specific date. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 Subscription restoration scheduled successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "scheduledAt": "2024-02-01", "metadata": { "propertyName": "string" } }' ``` #### [POST /subscriptions/{subscriptionId}/block-sim](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/block-sim) Block SIM Block the SIM card on a subscription, so it can no longer use the network. Use this when a subscriber reports their SIM lost or stolen. The block takes effect immediately and cannot be scheduled. Any changes already scheduled on the subscription are cancelled, except an in-progress number port or a scheduled SIM card change, which both continue — a cancelled port would lose the subscriber their number. Blocking is not reversible through this endpoint: issue a new SIM card to bring the subscription back into service. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Responses ###### 200 SIM blocked successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /subscriptions/{subscriptionId}/change-sim](/api-reference/subscriptions#tag/subscriptions/POST/subscriptions/{subscriptionId}/change-sim) Change subscription SIM card Change the SIM card (ICC/ICCID) for a subscription. This is used when replacing a lost, damaged, or upgraded SIM card. Supports flexible scheduling: - Immediate SIM card change - Next day SIM card change - Beginning of next month SIM card change - Specific date SIM card change Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `scheduledAt` (`string`, optional, date, example 2024-02-01) — Change the SIM card on a specific date. - `icc` (`string`, required, example 89012345678901234567) — The ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile. - `simCardType` (`enum`, required, one of PHYSICAL, ESIM, example PHYSICAL) — The type of SIM card being installed. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ##### Responses ###### 200 SIM card change scheduled successfully. Type: [Subscription](/api-reference/models.md#models/Subscription) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "scheduledAt": "2024-02-01", "icc": "89012345678901234567", "simCardType": "PHYSICAL", "metadata": { "propertyName": "string" } }' ``` #### [GET /subscriptions/{subscriptionId}/esim/qrcode](/api-reference/subscriptions#tag/subscriptions/GET/subscriptions/{subscriptionId}/esim/qrcode) Get eSIM QR code Retrieve QR code data and hosted URL for eSIM profile download. Returns both the raw QR code data (LPA format) and a hosted URL for the QR code image. Only available for eSIM subscriptions (`sim.esim: true`). QR codes expire for security and should be treated as sensitive data. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `subscriptionId` (`string`, required) — The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 eSIM QR code data and hosted URL retrieved successfully. Type: [EsimQrCode](/api-reference/models.md#models/EsimQrCode) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ### Tools Canonical URL: https://docs.telnesstech.com/api-reference/tools #### [POST /tools/validate-address](/api-reference/tools#tag/tools/POST/tools/validate-address) Validate address Validate an address and get suggestions for corrections if the address is invalid. This is particularly important for US addresses where precise addressing is required for service delivery and regulatory compliance. Depending on setup, address validation is either shape based (e.g. this looks like an address), or verified against an address registry. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. ##### Responses ###### 200 Address validation completed. Type: [AddressValidationResult](/api-reference/models.md#models/AddressValidationResult) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ###### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/tools/validate-address \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }' ``` #### [POST /tools/check-porting-eligibility](/api-reference/tools#tag/tools/POST/tools/check-porting-eligibility) Check number porting eligibility Check if a phone number is eligible for porting to this network. This helps validate numbers before creating subscription line items with porting details. Returns information about the current carrier and porting requirements. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `msisdn` (`string`, required, phone, example +15551234567) — The phone number to check for porting eligibility. ##### Responses ###### 200 Porting eligibility check completed. Type: [PortingEligibilityResult](/api-reference/models.md#models/PortingEligibilityResult) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ###### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/tools/check-porting-eligibility \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "msisdn": "+15551234567" }' ``` #### [POST /tools/get-device-info](/api-reference/tools#tag/tools/POST/tools/get-device-info) Get device information by IMEI Get detailed information about a device using its IMEI number. This helps validate device compatibility and capabilities before creating subscription line items. Particularly useful for eSIM activation requirements. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `imei` (`string`, required, example 356938035643809) — The International Mobile Equipment Identity of the device. ##### Responses ###### 200 Device information retrieved. Type: [DeviceInfo](/api-reference/models.md#models/DeviceInfo) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ###### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/api-reference/models.md#models/Error) ###### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/tools/get-device-info \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "imei": "356938035643809" }' ``` #### [POST /tools/search-devices](/api-reference/tools#tag/tools/POST/tools/search-devices) Find devices by name Find devices whose name matches a query, with the capabilities of each one. Use this when the customer knows their device by its everyday name and not by its IMEI. It answers whether each match supports eSIM, so the customer can pick the right SIM type before they order. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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. ##### Responses ###### 200 The matching devices. Type: [DeviceSearchResult](/api-reference/models.md#models/DeviceSearchResult) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ###### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/api-reference/models.md#models/Error) ###### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/tools/search-devices \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "query": "iPhone 15", "limit": 20 }' ``` #### [POST /tools/check-network-coverage](/api-reference/tools#tag/tools/POST/tools/check-network-coverage) Check network coverage Check network coverage quality and availability for a specific address. This helps customers understand service quality before placing orders and can provide product offering recommendations based on coverage. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. ##### Responses ###### 200 Network coverage information retrieved. Type: [NetworkCoverage](/api-reference/models.md#models/NetworkCoverage) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ###### 501 This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can. Type: [Error](/api-reference/models.md#models/Error) ###### 503 The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/tools/check-network-coverage \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "address": { "street1": "500 S Main St", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }' ``` ### Users Canonical URL: https://docs.telnesstech.com/api-reference/users #### [GET /users](/api-reference/users#tag/users/GET/users) List users List all users. Will return all users the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Query parameters - `filter` (`string`, optional) — A free text search string to filter users by name or email. - `customerId` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ##### Responses ###### 200 A list of users. Type: `object` - `items` (`array of User`, required) - `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` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/users \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [POST /users](/api-reference/users#tag/users/POST/users) Create user Create a new user. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) Type: `object` - `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) ##### Responses ###### 201 User created successfully. Type: [User](/api-reference/models.md#models/User) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/users \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "role": "ADMIN", "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "referenceId": "hr-employee-98765" }' ``` #### [GET /users/{userId}](/api-reference/users#tag/users/GET/users/{userId}) Get user Get a user by ID or referenceId. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `userId` (`string`, required) — The unique identifier of the user. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Responses ###### 200 User details. Type: [User](/api-reference/models.md#models/User) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/users/USER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### [PUT /users/{userId}](/api-reference/users#tag/users/PUT/users/{userId}) Update user Update an existing user. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ##### Path parameters - `userId` (`string`, required) — The unique identifier of the user. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ##### Request body (required) 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) ##### Responses ###### 200 User updated successfully. Type: [User](/api-reference/models.md#models/User) ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/users/USER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "metadata": { "propertyName": "string" } }' ``` ### Workflows Canonical URL: https://docs.telnesstech.com/api-reference/workflows #### [POST /workflows/webhook/{path...}](/api-reference/workflows#tag/workflows/POST/workflows/webhook/{path...}) Trigger workflow via webhook Trigger a registered workflow via webhook. The wildcard path is matched against registered workflow webhook paths. If at least one workflow is registered with the matching path, the request body is forwarded to the workflow(s) and a 200 response is returned. If no workflows match the provided path, a 400 Bad Request is returned. Authentication: Public ##### Path parameters - `path...` (`string`, required) — The wildcard webhook path to match against registered workflows. Leading slashes in the workflow registration are ignored, so `support/intents/reward/topup` and `/support/intents/reward/topup` are equivalent. This is a greedy path parameter, meaning it captures the entire remainder of the URL path. ##### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ##### Request body (required) The webhook payload. Can be any valid JSON object. The payload data is passed to the matching workflow(s) which can access and use any properties from it. Type: `object` - `propertyName` (`any`, optional) — Any additional properties, passed through as given. ##### Responses ###### 200 Webhook successfully delivered to at least one registered workflow. Type: `object` - `workflowTasks` (`array of EmbeddedWorkflowTask`, required) — List of workflow tasks that were triggered by this webhook. - `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. ###### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) ###### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) ###### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) ###### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ###### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) ###### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ##### Example request ```bash curl https://apiv2.example.com/api/v2/workflows/webhook/support/intents/reward/topup \ --request POST \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Webhook events Canonical URL: https://docs.telnesstech.com/api-reference/webhook-events ### Custom #### [custom.workflow_triggered](/api-reference/webhook-events#tag/custom/webhook/POST/customworkflow-triggered) Custom workflow triggered Sent from within a workflow and content is defined by the workflow configuration. ##### Request body (required) 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` (`const "custom.workflow_triggered"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`array of object`, required) — A list of key value pairs defined by the workflow configuration. Always includes a "customType" entry with the custom event type (e.g. "telna.esim_status_change"). - `key` (`string`, required) — The key of the data item. - `value` (`string`, required) — The value of the data item. ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Customers Manage customers. #### [customer.created](/api-reference/webhook-events#tag/customers/webhook/POST/customercreated) Customer created Sent when a new customer is created in the system. ##### Request body (required) 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` (`const "customer.created"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Customer snapshot at the time of this event. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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 to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [customer.updated](/api-reference/webhook-events#tag/customers/webhook/POST/customerupdated) Customer updated Sent when customer information is modified, including profile changes, billing updates, or status changes. ##### Request body (required) 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` (`const "customer.updated"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Customer snapshot at the time of this event. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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 to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [customer.deleted](/api-reference/webhook-events#tag/customers/webhook/POST/customerdeleted) Customer deleted Sent when a customer account is permanently deleted from the system. ##### Request body (required) 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` (`const "customer.deleted"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Customer snapshot at the time of this event. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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 to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `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. - `street1` (`string`, required, example 500 S Main St) — 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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Licenses Manage licenses. #### [license.created](/api-reference/webhook-events#tag/licenses/webhook/POST/licensecreated) License created Sent when a license is created. ##### Request body (required) 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` (`const "license.created"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — License snapshot. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [license.updated](/api-reference/webhook-events#tag/licenses/webhook/POST/licenseupdated) License updated Sent when a license changes. ##### Request body (required) 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` (`const "license.updated"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Updated license snapshot. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [license.cancelled](/api-reference/webhook-events#tag/licenses/webhook/POST/licensecancelled) License cancelled Sent when a license cancellation is confirmed. ##### Request body (required) 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` (`const "license.cancelled"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — License snapshot at the time of this event. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [license.activated](/api-reference/webhook-events#tag/licenses/webhook/POST/licenseactivated) License activated Sent when a license becomes ACTIVE. ##### Request body (required) 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` (`const "license.activated"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Active license snapshot. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [license.renewed](/api-reference/webhook-events#tag/licenses/webhook/POST/licenserenewed) License renewed Sent when a license renews into a new term/period. ##### Request body (required) 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` (`const "license.renewed"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — License snapshot at renewal. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [license.ended](/api-reference/webhook-events#tag/licenses/webhook/POST/licenseended) License ended Sent when a license reaches final end state. ##### Request body (required) 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` (`const "license.ended"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Final license snapshot. — A license represents a permission to use a software product with embedded customer and product offering details. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Orders Manage orders and line items. #### [order.created](/api-reference/webhook-events#tag/orders/webhook/POST/ordercreated) Order created Sent when an order is created. ##### Request body (required) 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` (`const "order.created"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Order snapshot at creation. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.updated](/api-reference/webhook-events#tag/orders/webhook/POST/orderupdated) Order updated Sent when an order changes (line items, metadata, pricing recalculation). ##### Request body (required) 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` (`const "order.updated"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Updated order snapshot. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.cancelled](/api-reference/webhook-events#tag/orders/webhook/POST/ordercancelled) Order cancelled Sent when an order is cancelled. ##### Request body (required) 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` (`const "order.cancelled"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Cancelled order snapshot. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.statusChanged](/api-reference/webhook-events#tag/orders/webhook/POST/orderstatuschanged) Order status changed Sent when an order status transitions (e.g. PENDING -> SUBMITTED, PROCESSING -> COMPLETED, etc.). ##### Request body (required) 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` (`const "order.statusChanged"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Order snapshot at the time of this event. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.submitted](/api-reference/webhook-events#tag/orders/webhook/POST/ordersubmitted) Order submitted Sent when an order is formally submitted for processing/fulfillment. ##### Request body (required) 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` (`const "order.submitted"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Order snapshot at submission. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.expired](/api-reference/webhook-events#tag/orders/webhook/POST/orderexpired) Order expired Sent when an order expires before completion. ##### Request body (required) 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` (`const "order.expired"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Expired order snapshot. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [order.lineItemStatusChanged](/api-reference/webhook-events#tag/orders/webhook/POST/orderlineitemstatuschanged) Order line item status changed Sent when a single line item within an order changes fulfillment status (e.g. PENDING -> RUNNING -> COMPLETED or RUNNING -> FAILED). Triggered independently of the order's overall status; an order can complete while individual line items continue running or end in FAILED. ##### Request body (required) 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` (`const "order.lineItemStatusChanged"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) - `order` (`object`, required) — Order snapshot at the time of this event. — 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) - `lineItemId` (`string`, required, example line-item-1) — The line item within the order whose status changed. - `status` (`enum`, required, one of PENDING, RUNNING, COMPLETED, FAILED) — 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. ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Reports Retrieve generated reports and download their files. #### [report.ready](/api-reference/webhook-events#tag/reports/webhook/POST/reportready) Report ready Sent when a report has finished generating and its file is ready to download. Fetch the report by its identifier to obtain a time-limited download link. ##### Request body (required) 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` (`const "report.ready"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — The report that just became ready, including a time-limited download link. — 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. - `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. ##### Responses ###### 200 Webhook acknowledged - no further retries will be attempted. ###### 4XX Temporary failure - delivery will be retried with backoff. ###### 5XX Temporary failure - delivery will be retried with backoff. ### Subscription Port-In #### [subscription.portIn.created](/api-reference/webhook-events#tag/subscription-port-in/webhook/POST/subscriptionportincreated) Subscription port-in initiated Sent when a port-in request is created for a subscription. ##### Request body (required) 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` (`const "subscription.portIn.created"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot including porting embed. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.portIn.updated](/api-reference/webhook-events#tag/subscription-port-in/webhook/POST/subscriptionportinupdated) Subscription port-in updated Sent when port-in details (schedule, status) change. ##### Request body (required) 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` (`const "subscription.portIn.updated"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Updated subscription snapshot (porting section changed). — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.portIn.completed](/api-reference/webhook-events#tag/subscription-port-in/webhook/POST/subscriptionportincompleted) Subscription port-in completed Sent when the number porting completes successfully. ##### Request body (required) 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` (`const "subscription.portIn.completed"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.portIn.failed](/api-reference/webhook-events#tag/subscription-port-in/webhook/POST/subscriptionportinfailed) Subscription port-in failed Sent when a number port-in attempt fails irrecoverably or requires manual intervention. ##### Request body (required) 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` (`const "subscription.portIn.failed"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot including failed porting state. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Subscription Usage Get subscription usage. #### [subscription.quotaNotification](/api-reference/webhook-events#tag/subscription-usage/webhook/POST/subscriptionquotanotification) Subscription quota threshold exceeded Sent when a subscription quota threshold is exceeded (e.g. 80%, 100% of data, SMS, or voice allowance). ##### Request body (required) 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` (`const "subscription.quotaNotification"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ### Subscriptions Manage subscriptions and subscription. #### [subscription.created](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptioncreated) Subscription created Sent when a new subscription has been successfully created. ##### Request body (required) 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` (`const "subscription.created"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Webhook acknowledged - no further retries will be attempted. ###### 4XX Temporary failure - delivery will be retried with backoff. ###### 5XX Temporary failure - delivery will be retried with backoff. #### [subscription.updated](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptionupdated) Subscription updated Sent when mutable fields on an existing subscription are changed (e.g. status transition, product offering change, MSISDN assignment, metadata updates). ##### Request body (required) 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` (`const "subscription.updated"`, required) — The event type identifier. - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Webhook acknowledged - no further retries will be attempted. ###### 4XX Temporary failure - delivery will be retried with backoff. ###### 5XX Temporary failure - delivery will be retried with backoff. #### [subscription.cancelled](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptioncancelled) Subscription cancelled Sent when a subscription cancellation is confirmed (end-of-term or immediate as applicable). ##### Request body (required) 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` (`const "subscription.cancelled"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.activated](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptionactivated) Subscription activated Sent when a subscription enters ACTIVE state. ##### Request body (required) 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` (`const "subscription.activated"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Current subscription in ACTIVE state. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.renewed](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptionrenewed) Subscription renewed Sent when a subscription successfully renews into a new billing period/term. ##### Request body (required) 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` (`const "subscription.renewed"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at start of new term/period. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.ended](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptionended) Subscription ended Sent when a subscription reaches its final end (no longer billable / usable). ##### Request body (required) 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` (`const "subscription.ended"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Final subscription state. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry #### [subscription.subscriber_set](/api-reference/webhook-events#tag/subscriptions/webhook/POST/subscriptionsubscriber-set) Subscription subscriber set Sent when a subscriber is assigned to a subscription. ##### Request body (required) 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` (`const "subscription.subscriber_set"`, required) - `occurredAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — RFC 3339 timestamp when the underlying change occurred. - `data` (`object`, required) — Subscription snapshot at the time of this event. — A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. - `subscriptionId` (`string`, required, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier for the subscription. - `referenceId` (`string`, optional, max length 255, example crm-subscription-12345) — A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. - `status` (`enum`, 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) ##### Responses ###### 200 Acknowledged ###### 4XX Temporary failure - will retry ###### 5XX Temporary failure - will retry ## Schemas Canonical URL: https://docs.telnesstech.com/api-reference/models ### [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, example not_found) — A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer `internalCode` for branching. - `internalCode` (`string`, optional, example 4009) — Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code. - `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` - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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 to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `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. - `street1` (`string`, required, example 500 S Main St) — 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) ### [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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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 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, 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 - `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 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, 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 - `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, 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 - `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`). ### [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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. ### [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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. ### [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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. ### [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` - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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. - `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, 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 - `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, 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 - `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`). - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) — Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) — Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) — Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. Type: `one of` - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, required) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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, 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 - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, required) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `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. - `balance` (`number`, optional, double, deprecated, example 15.5) — Deprecated. Use `balanceMinor` instead. Remaining prepaid amount available for international long distance calls, in major units of the currency given by `currency`. - `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. - `balance` (`number`, optional, double, deprecated, example 15.5) — Deprecated. Use `balanceMinor` instead. Remaining prepaid amount available for international long distance calls, in major units of the currency given by `currency`. - `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. - `balance` (`number`, optional, double, deprecated, example 15.5) — Deprecated. Use `balanceMinor` instead. Remaining prepaid amount available for international long distance calls, in major units of the currency given by `currency`. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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` (`one of`, optional) — Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type. - `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. - `discount` (`number`, optional, decimal, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. - `discountMinor` (`integer`, optional, int64, deprecated) — Deprecated. The API no longer sends this field. To find the discounts that an offering has, read `standardDiscount`, `bindingContract.discount` and `customUpfrontPayment.discount`. To find what a customer pays, price an order. This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field. - `netPrice` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `netPriceMinor` instead. The configured price of the offering, in major currency units. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, 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). - `boundMonths` (`integer`, optional, deprecated, example 12) — Deprecated. Use `bindingContract.duration` instead. Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means 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. - `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. - `currencyOptions` (`object with string keys`, optional, deprecated) — Deprecated. Use `currencyOptionsMinor` instead. Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units. - `*` (`number`, optional, decimal) - `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, 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 - `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) Assignment reference for a license, indicating what entity the license is assigned to. This is a simplified version for list operations - use EmbeddedAssignedTo for detailed views. 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. Note: this endpoint is disabled when Seamless OS manages billing, licenses can then be created by orders. Type: `object` - `productOfferingId` (`string`, required, example a7b8c9d0-e1f2-3456-7890-bcdef0123456) — The unique identifier for the product offering to subscribe to. This controls what type of license is being created. - `customerId` (`string`, required, uuid, example b8c9d0e1-f2a3-4567-8901-cdef01234567) — The unique identifier for the existing customer who will own this license. - `licenseType` (`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. - `assignedTo` (`one of`, required) — Assignment reference for a license, indicating what entity the license is assigned to. This is a simplified version for list operations - use EmbeddedAssignedTo for detailed views. - `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 should be activated. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Final order total including all taxes and fees, in major currency units. - `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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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) ### [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. - `street1` (`string`, required, example 500 S Main St) — 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. ### [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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. ### [SubscriptionChangeLineItem](/api-reference/models#models/SubscriptionChangeLineItem) Line item for changing a subscription's product offering. Type: `object` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. ### [AddonChangeLineItem](/api-reference/models#models/AddonChangeLineItem) Line item for changing an add-on's product offering. Type: `object` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 `promo_code_not_redeemable` 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. ### [OrderPricingSummary](/api-reference/models#models/OrderPricingSummary) The price of an order. In regions with complex tax rules (e.g., the US), you need to call the price calculation endpoint to get accurate tax amounts before submitting the order. In other regions, tax is dependent on customer type but typically included. All amounts are in minor units of the currency (e.g., 13739 = $137.39 when the currency is USD). Type: `object` - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. ### [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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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` - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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) ### [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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `subtotal` (`number`, optional, decimal, deprecated, example 125.99) — Deprecated. Use `subtotalMinor` instead. Subtotal after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 12599) — Subtotal after discounts and before taxes and fees, in minor currency units. Add the `totalDiscountsMinor` of each line item to it to get the amount before discounts. - `taxAmount` (`number`, optional, decimal, deprecated, example 10.08) — Deprecated. Use `taxAmountMinor` instead. Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately. - `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. - `total` (`number`, optional, decimal, deprecated, example 137.39) — Deprecated. Use `totalMinor` instead. Total amount due for the order, in major currency units. - `totalMinor` (`integer`, required, int64, example 13739) — Total amount due for the order, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Recurring subtotal after discounts and before taxes, in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 2999) — Recurring subtotal after discounts and before taxes, in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 32.39) — Deprecated. Use `totalMinor` instead. Total estimated recurring amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 3239) — Total estimated recurring amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on recurring charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `subtotalMinor` instead. First invoice subtotal (e.g., prorated amount, setup fees), in major currency units. - `subtotalMinor` (`integer`, optional, int64, example 1450) — First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units. - `total` (`number`, optional, decimal, deprecated, example 15.66) — Deprecated. Use `totalMinor` instead. Total first invoice amount, in major currency units. - `totalMinor` (`integer`, optional, int64, example 1566) — Total first invoice amount, in minor currency units. - `taxAmount` (`number`, optional, decimal, deprecated, example 1.16) — Deprecated. Use `taxAmountMinor` instead. Estimated tax on initial invoice charges, in major currency units. Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here. - `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 taxes are included in the total. - `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. - `subtotal` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `subtotalMinor` instead. Amount for this line item after discounts and before taxes and fees, in major currency units. - `subtotalMinor` (`integer`, required, int64, example 2999) — Amount for this line item after discounts and before taxes and fees, in minor currency units. Add `totalDiscountsMinor` to it to get the amount before discounts. - `total` (`number`, optional, decimal, deprecated, example 27.47) — Deprecated. Use `totalMinor` instead. Amount due for this line item after taxes, fees, and discounts, in major currency units. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `taxAmount` (`number`, optional, decimal, deprecated, example 2.47) — Deprecated. Use `taxAmountMinor` instead. Total taxes for this line item, in major currency units. - `taxAmountMinor` (`integer`, optional, int64, example 247) — Total taxes for this line item, in minor currency units. - `taxIncluded` (`boolean`, optional, example true) — Whether taxes are included in the total. - `discounts` (`array of object`, optional) — The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion code, a price list reduction or a binding period discount. - `name` (`string`, required, example First month free) — Discount name or description. - `amount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `amountMinor` instead. Discount amount (positive value), in major currency units. - `amountMinor` (`integer`, required, int64, example 2999) — Discount amount (positive value), in minor currency units. - `totalDiscounts` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `totalDiscountsMinor` instead. Total discounts for this line item, in major currency units. - `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. - `recurringAmount` (`number`, optional, decimal, deprecated, example 29.99) — Deprecated. Use `recurringAmountMinor` instead. Recurring cost for this line item per billing cycle, in major currency units. - `recurringAmountMinor` (`integer`, optional, int64, example 2999) — Recurring cost for this line item per billing cycle, in minor currency units. - `initialInvoiceAmount` (`number`, optional, decimal, deprecated, example 14.5) — Deprecated. Use `initialInvoiceAmountMinor` instead. Amount for this line item on the first invoice when different from recurring, in major currency units. - `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. - `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) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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 `promo_code_not_redeemable` 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. Optional while the order is a draft, but must be provided before the order can be submitted. - `esim` (`boolean`, required, example true) — Whether this subscription should use 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. - `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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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 whose product offering this line item changes. - `productOfferingId` (`string`, required, example mobile-plan-premium) — New product offering to change to. - `scheduleDate` (`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) - `status` (`enum`, optional, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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 product offering change for 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. - `productOfferingId` (`string`, required, example addon-data-5gb) — New add-on product offering to change to. - `scheduleDate` (`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 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, one of PENDING, RUNNING, COMPLETED, FAILED) — Server-resolved fulfillment status for this line item. — 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. ### [InvoiceStatus](/api-reference/models#models/InvoiceStatus) Current stage of the invoice lifecycle. - DRAFT: Being prepared; not yet visible to the customer. - SENT: Delivered to the customer and awaiting payment. - PAID: Payment has been received. - VOID: Canceled and no longer collectible. - OVERDUE: Past its due date without payment. Type: `enum` ### [InvoiceListItem](/api-reference/models#models/InvoiceListItem) An invoice summary without its line items, optimized for list views. Fetch the individual invoice for the full line item breakdown. 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 is for. - `invoiceNumber` (`string`, required, example INV-2024-001) — Human-readable invoice number. - `status` (`enum`, required, one of DRAFT, SENT, PAID, VOID, OVERDUE, example SENT) — Current status of the invoice. — Current stage of the invoice lifecycle. - DRAFT: Being prepared; not yet visible to the customer. - SENT: Delivered to the customer and awaiting payment. - PAID: Payment has been received. - VOID: Canceled and no longer collectible. - OVERDUE: Past its due date without payment. - `dueDate` (`string`, required, date, example 2024-02-15) — When payment is due. - `subtotalAmountMinor` (`integer`, optional, int64, example 2999) — Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD). - `totalAmountMinor` (`integer`, optional, int64, example 2989) — Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units. - `currency` (`string`, optional, example USD) — The ISO 4217 currency code for all invoice amounts (e.g., "USD"). - `sentAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the invoice was sent to the customer (if status is sent or later). - `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the invoice was paid (if status is paid). - `voidedAt` (`string`, optional, date-time, example 2024-02-05T09:00:00Z) — When the invoice was voided (if status is void). - `invoiceUrl` (`string`, optional, uri, example https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d) — Hosted URL where customer can view the invoice. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice 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) ### [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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. ### [Invoice](/api-reference/models#models/Invoice) An invoice with detailed line item breakdown that can be sent to customers for payment. 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 is for. - `invoiceNumber` (`string`, required, example INV-2024-001) — Human-readable invoice number. - `status` (`enum`, required, one of DRAFT, SENT, PAID, VOID, OVERDUE, example SENT) — Current status of the invoice. — Current stage of the invoice lifecycle. - DRAFT: Being prepared; not yet visible to the customer. - SENT: Delivered to the customer and awaiting payment. - PAID: Payment has been received. - VOID: Canceled and no longer collectible. - OVERDUE: Past its due date without payment. - `dueDate` (`string`, required, date, example 2024-02-15) — When payment is due. - `lineItems` (`array of InvoiceLineItem`, required) — Detailed breakdown of items included in this invoice. - `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. - `amount` (`number`, optional, decimal, deprecated, example 2.4) — Deprecated. Use `amountMinor` instead. The amount charged for this tax component, in major units of the currency of the transaction. - `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. - `subtotalAmountMinor` (`integer`, optional, int64, example 2999) — Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD). - `taxAmountMinor` (`integer`, optional, int64, example 240) — Total tax amount for the invoice, in minor currency units. - `feeAmountMinor` (`integer`, optional, int64, example 250) — Total fee amount for the invoice, in minor currency units. - `discountAmountMinor` (`integer`, optional, int64, example 500) — Total amount deducted by discounts (positive value), in minor currency units. - `totalAmountMinor` (`integer`, optional, int64, example 2989) — Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units. - `currency` (`string`, optional, example USD) — The ISO 4217 currency code for all invoice amounts (e.g., "USD"). - `sentAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the invoice was sent to the customer (if status is sent or later). - `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the invoice was paid (if status is paid). - `voidedAt` (`string`, optional, date-time, example 2024-02-05T09:00:00Z) — When the invoice was voided (if status is void). - `invoiceUrl` (`string`, optional, uri, example https://invoices.yourapp.com/inv_123e4567) — Hosted URL where customer can view the invoice. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice 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) ### [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` ### [PaymentProvider](/api-reference/models#models/PaymentProvider) Payment service provider that processes the transaction. 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) ### [PaymentIntentStatus](/api-reference/models#models/PaymentIntentStatus) Current stage of a payment intent as it is collected through the payment provider. - 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` ### [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 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. - 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. - `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. ### [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 and taxes, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). - `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. ### [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, 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 record of an amount being collected from a customer over card rails, with the charge attempts, refunds, and billed line items that show how collection went. A payment intent is created automatically when payment collection starts for an order, whether through a payment session or a payment link; you do not create one directly. Read it to see what was charged, retried, or refunded. To start collecting payment, create a payment session (customer present in your checkout) or a payment link (shareable hosted page) instead. 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 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. - 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 and taxes, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). - `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. - `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, 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. ### [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 create a hosted checkout session. Currently all payment sessions use the hosted checkout flow, so a hosted payment page URL is always returned regardless of this value. - `returnUrl` (`string`, required, example https://example.com/order/confirmation) — The URL the customer is redirected to after completing payment on the hosted page. 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. - `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) ### [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 and redirect the customer to hostedUrl to pay; once the session completes, pass its paymentSessionId when submitting the order. 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`, required, 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. - `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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. - `street1` (`string`, required, example 500 S Main St) — 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. ### [CheckNetworkCoverageRequest](/api-reference/models#models/CheckNetworkCoverageRequest) Request to check network coverage for 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. - `street1` (`string`, required, example 500 S Main St) — 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. ### [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 specific address. 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 postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street1` (`string`, required, example 500 S Main St) — 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. - `coverageLevel` (`enum`, required, one of EXCELLENT, GOOD, FAIR, POOR, NO_COVERAGE, example GOOD) — Overall network coverage quality at this location. - `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. ### [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. - `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. - `data` (`any`, required) — Event-specific payload; structure depends on event type.