--- title: Webhook events description: Every event the API sends, grouped by the resource that emits it. --- # Webhook events Every event the API sends, grouped by the resource that emits it. ## 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