Webhook events
Custom
Custom workflow triggered
custom.workflow_triggeredSent from within a workflow and content is defined by the workflow configuration.
We POST this body to the endpoint you registered for custom.workflow_triggered.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "custom.workflow_triggered"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataarray of objectrequiredA 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").
Show child attributes
keystringrequiredThe key of the data item.
valuestringrequiredThe value of the data item.
Acknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "custom.workflow_triggered",
"occurredAt": "2024-01-15T10:30:00Z",
"data": [
{
"key": "string",
"value": "string"
}
]
}Customers
Manage customers.
Customer created
customer.createdSent when a new customer is created in the system.
We POST this body to the endpoint you registered for customer.created.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "customer.created"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredCustomer 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.
Show child attributes
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe 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.
identitystringA 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.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A 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.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailThe primary contact email for the customer.
msisdnstringphoneThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow 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.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe 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.
Show child attributes
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
contactobjectThe 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.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
shippingobjectThe 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.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "customer.created",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"name": "John Doe",
"identity": "12-3456789",
"preferredLocale": "en-US",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "E_INVOICE",
"email": "billing@company.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"autoPay": true
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"metadata": {
"propertyName": "string"
}
}
}Customer updated
customer.updatedSent when customer information is modified, including profile changes, billing updates, or status changes.
We POST this body to the endpoint you registered for customer.updated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "customer.updated"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredCustomer 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.
Show child attributes
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe 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.
identitystringA 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.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A 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.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailThe primary contact email for the customer.
msisdnstringphoneThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow 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.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe 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.
Show child attributes
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
contactobjectThe 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.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
shippingobjectThe 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.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "customer.updated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"name": "John Doe",
"identity": "12-3456789",
"preferredLocale": "en-US",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "E_INVOICE",
"email": "billing@company.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"autoPay": true
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"metadata": {
"propertyName": "string"
}
}
}Customer deleted
customer.deletedSent when a customer account is permanently deleted from the system.
We POST this body to the endpoint you registered for customer.deleted.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "customer.deleted"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredCustomer 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.
Show child attributes
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe 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.
identitystringA 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.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A 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.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailThe primary contact email for the customer.
msisdnstringphoneThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow 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.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe 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.
Show child attributes
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
contactobjectThe 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.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>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.
values
MEMBERMANAGERADMIN
shippingobjectThe 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.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "customer.deleted",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"name": "John Doe",
"identity": "12-3456789",
"preferredLocale": "en-US",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "E_INVOICE",
"email": "billing@company.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"autoPay": true
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"metadata": {
"propertyName": "string"
}
}
}Licenses
Manage licenses.
License created
license.createdSent when a license is created.
We POST this body to the endpoint you registered for license.created.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.created"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredLicense snapshot.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.created",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}License updated
license.updatedSent when a license changes.
We POST this body to the endpoint you registered for license.updated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.updated"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredUpdated license snapshot.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.updated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}License cancelled
license.cancelledSent when a license cancellation is confirmed.
We POST this body to the endpoint you registered for license.cancelled.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.cancelled"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredLicense snapshot at the time of this event.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.cancelled",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}License activated
license.activatedSent when a license becomes ACTIVE.
We POST this body to the endpoint you registered for license.activated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.activated"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredActive license snapshot.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.activated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}License renewed
license.renewedSent when a license renews into a new term/period.
We POST this body to the endpoint you registered for license.renewed.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.renewed"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredLicense snapshot at renewal.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.renewed",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}License ended
license.endedSent when a license reaches final end state.
We POST this body to the endpoint you registered for license.ended.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "license.ended"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredFinal license snapshot.
A license represents a permission to use a software product with embedded customer and product offering details.
Show child attributes
licensestringrequiredThe unique identifier for the license.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
typestringrequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
assignedone ofAssignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.
Show child attributes
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
subscriptionstringrequiredThe unique identifier for the subscription
subscriptionstringDisplay name for the subscription (typically the phone number)
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
activatedstringdaterequiredThe date when the license was activated.
cancelledstringdateThe date when the license was canceled (if applicable).
pausedstringdateThe date when the license was paused (if applicable).
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "license.ended",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"status": "PENDING",
"type": "PBX_USER_LEVEL",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"assignedTo": {
"type": "SUBSCRIPTION",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"subscriptionDisplay": "+1 (555) 123-4567"
},
"details": {},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"pausedAt": "2024-03-01",
"metadata": {
"propertyName": "string"
}
}
}Orders
Manage orders and line items.
Order created
order.createdSent when an order is created.
We POST this body to the endpoint you registered for order.created.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.created"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredOrder 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.created",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order updated
order.updatedSent when an order changes (line items, metadata, pricing recalculation).
We POST this body to the endpoint you registered for order.updated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.updated"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredUpdated 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.updated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order cancelled
order.cancelledSent when an order is cancelled.
We POST this body to the endpoint you registered for order.cancelled.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.cancelled"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredCancelled 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.cancelled",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order status changed
order.statusChangedSent when an order status transitions (e.g. PENDING -> SUBMITTED, PROCESSING -> COMPLETED, etc.).
We POST this body to the endpoint you registered for order.statusChanged.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.statusChanged"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredOrder 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.statusChanged",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order submitted
order.submittedSent when an order is formally submitted for processing/fulfillment.
We POST this body to the endpoint you registered for order.submitted.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.submitted"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredOrder 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.submitted",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order expired
order.expiredSent when an order expires before completion.
We POST this body to the endpoint you registered for order.expired.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.expired"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredExpired 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
userstringThe user's identifier, once the user exists.
namestringThe user's full name.
emailstringemailThe email the user logs in with.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
customerstringThe unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredCustomer name.
newbooleanrequiredIndicates if the customer was/will be created as part of order fulfillment.
billingobjectBilling 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.
Show child attributes
namestringBilling contact name.
emailstringemailBilling contact email.
addressobjectA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonePhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
*stringlinearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
subtotalnumberdecimaldeprecatedDeprecated. Use subtotalMinor instead.
Subtotal after discounts and before taxes and fees, in major currency units.
subtotalintegerint64Subtotal 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.
taxnumberdecimaldeprecatedDeprecated. Use taxAmountMinor instead.
Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
totalnumberdecimaldeprecatedDeprecated. Use totalMinor instead.
Total amount due for the order, in major currency units.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
taxbooleanWhether taxes are included in the total.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
recurringobjectExpected 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.
Show child attributes
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
calculatedstringdate-timerequiredWhen the pricing was last calculated.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
isbooleanrequiredWhether the order is valid and ready for submission.
missingarray of stringRequired fields that are still missing.
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
linearray of objectValidation status for each line item.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
requiresenum<string>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.
values
NOT_REQUIREDOPTIONALREQUIRED
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
referencestringReference from the external payment system.
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.expired",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Order line item status changed
order.lineItemStatusChangedSent 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.
We POST this body to the endpoint you registered for order.lineItemStatusChanged.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "order.lineItemStatusChanged"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredShow child attributes
orderobjectrequiredOrder 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.
Show child attributes
orderstringrequiredUnique identifier for the order.
stateenum<string>requiredThe 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
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
userobjectThe 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.
Show child attributes
customerobjectThe customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
Show child attributes
billingobjectBilling 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.
Show child attributes
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
promostringPromotional code applied to this order, if any.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
consentsobject with string keysThe 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.
Show child attributes
linearray of OrderLineItemrequiredLine items in the order.
Show child attributes
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
validationobjectrequiredValidation status of the order and its line items.
Show child attributes
requirementsobjectrequiredWhat 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.
Show child attributes
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
submittedstringdate-timeWhen the order was submitted for fulfillment.
completedstringdate-timeWhen the order was completed.
createdobjectEntities created as part of order fulfillment.
Show child attributes
createdstringdate-timerequiredWhen the order was created.
updatedstringdate-timerequiredWhen the order was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
linestringrequiredThe line item within the order whose status changed.
statusenum<string>requiredThe 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.
values
PENDINGRUNNINGCOMPLETEDFAILED
Acknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "order.lineItemStatusChanged",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"order": {
"orderId": "order-123",
"state": "PENDING",
"user": {
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "John Doe",
"email": "john.doe@example.com",
"newUser": true
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"billing": {
"name": "John Doe",
"email": "billing@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"shipping": {
"name": "John Doe",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"instructions": "Leave at front door"
},
"promoCode": "STUDENT2024",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"consents": {
"termsOfService": "true",
"marketing": "true"
},
"lineItems": [
{
"type": "SUBSCRIPTION",
"lineItemId": "line-item-1",
"productOfferingId": "mobile-plan-basic",
"msisdn": "+15551234567",
"leaseToken": "lease_8f3b1c2d4e5f6789",
"tempNumber": true,
"portingRequested": true,
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"extensions": {
"propertyName": "string"
},
"display": "John Doe - Work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8931440400000000000"
},
"scheduleActivationAt": "2024-02-01",
"activateOnDemand": true,
"metadata": {
"propertyName": "string"
},
"status": "PENDING"
}
],
"pricing": {
"subtotal": 125.99,
"subtotalMinor": 12599,
"taxAmount": 10.08,
"taxAmountMinor": 1008,
"total": 137.39,
"totalMinor": 13739,
"taxIncluded": true,
"currency": "USD",
"recurringCosts": {
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 32.39,
"totalMinor": 3239,
"taxAmount": 2.4,
"taxAmountMinor": 240,
"taxIncluded": true,
"billingCycle": {
"period": "MONTHLY",
"interval": 1
}
},
"initialInvoice": {
"subtotal": 14.5,
"subtotalMinor": 1450,
"total": 15.66,
"totalMinor": 1566,
"taxAmount": 1.16,
"taxAmountMinor": 116,
"taxIncluded": true,
"period": {
"start": "2024-01-15",
"end": "2024-01-31"
}
},
"calculatedAt": "2024-01-15T10:30:00Z",
"lineItems": [
{
"lineItemId": "line-item-1",
"subtotal": 29.99,
"subtotalMinor": 2999,
"total": 27.47,
"totalMinor": 2747,
"taxBreakdown": [
{
"description": "Sales Tax",
"amount": 2.4,
"amountMinor": 240,
"rate": 8.25
}
],
"taxAmount": 2.47,
"taxAmountMinor": 247,
"taxIncluded": true,
"discounts": [
{
"name": "First month free",
"amount": 29.99,
"amountMinor": 2999
}
],
"totalDiscounts": 29.99,
"totalDiscountsMinor": 2999,
"description": "Premium Plan",
"recurringAmount": 29.99,
"recurringAmountMinor": 2999,
"initialInvoiceAmount": 14.5,
"initialInvoiceAmountMinor": 1450
}
]
},
"validation": {
"isValid": false,
"missingFields": [
"customer",
"billing.address"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
],
"lineItemValidation": [
{
"lineItemId": "line-item-1",
"isValid": false,
"missingFields": [
"subscriber.name",
"sim.iccid"
],
"errors": [
{
"message": "Subscriber name is required.",
"property": "subscriber.name"
}
]
}
]
},
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"externalPayment": {
"reference": "ext-payment-ref-123",
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z"
},
"expiresAt": "2024-01-22T10:30:00Z",
"submittedAt": "2024-01-15T14:30:00Z",
"completedAt": "2024-01-15T15:00:00Z",
"createdEntities": {
"subscriptions": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"addons": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"productOfferingGroupId": "extra-data-packages",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"addedAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T09:00:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"metadata": {
"propertyName": "string"
},
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"type": "SUBSCRIPTION_CHANGE",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"newProductOfferingId": "po_mobile_premium_plus",
"appliedAt": "2024-01-15T15:00:00Z",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
},
"lineItemId": "line-item-1",
"status": "PENDING"
}
}Reports
Retrieve generated reports and download their files.
Report ready
report.readySent 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.
We POST this body to the endpoint you registered for report.ready.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "report.ready"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredThe 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.
Show child attributes
reportstringuuidrequiredThe unique identifier for this report run.
reportstringrequiredIdentifies which report was generated.
statusenum<string>requiredThe current stage of a report run in its lifecycle.
values
QUEUEDRUNNINGSUCCEEDEDFAILED
downloadstring | nullurirequiredA 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.
createdstringdate-timerequiredWhen the report run was requested.
completedstring | nulldate-timerequiredWhen the report run finished generating. Null while it is still in progress.
Acknowledgement
200Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
4XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
5XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "report.ready",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"reportKey": "subscriber_base_and_revenue",
"status": "QUEUED",
"downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...",
"createdAt": "2024-01-15T10:30:00Z",
"completedAt": "2024-01-15T10:30:00Z"
}
}Subscription Port-In
Subscription port-in initiated
subscription.portIn.createdSent when a port-in request is created for a subscription.
We POST this body to the endpoint you registered for subscription.portIn.created.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.portIn.created"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot including porting embed.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.portIn.created",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription port-in updated
subscription.portIn.updatedSent when port-in details (schedule, status) change.
We POST this body to the endpoint you registered for subscription.portIn.updated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.portIn.updated"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredUpdated subscription snapshot (porting section changed).
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.portIn.updated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription port-in completed
subscription.portIn.completedSent when the number porting completes successfully.
We POST this body to the endpoint you registered for subscription.portIn.completed.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.portIn.completed"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.portIn.completed",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription port-in failed
subscription.portIn.failedSent when a number port-in attempt fails irrecoverably or requires manual intervention.
We POST this body to the endpoint you registered for subscription.portIn.failed.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.portIn.failed"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot including failed porting state.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.portIn.failed",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription Usage
Get subscription usage.
Subscription quota threshold exceeded
subscription.quotaNotificationSent when a subscription quota threshold is exceeded (e.g. 80%, 100% of data, SMS, or voice allowance).
We POST this body to the endpoint you registered for subscription.quotaNotification.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.quotaNotification"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.quotaNotification",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscriptions
Manage subscriptions and subscription.
Subscription created
subscription.createdSent when a new subscription has been successfully created.
We POST this body to the endpoint you registered for subscription.created.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.created"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
4XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
5XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.created",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription updated
subscription.updatedSent when mutable fields on an existing subscription are changed (e.g. status transition, product offering change, MSISDN assignment, metadata updates).
We POST this body to the endpoint you registered for subscription.updated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.updated"requiredThe event type identifier.
occurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
Webhook acknowledged - no further retries will be attempted.
4XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
5XXTemporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
Temporary failure - delivery will be retried with backoff.
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.updated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription cancelled
subscription.cancelledSent when a subscription cancellation is confirmed (end-of-term or immediate as applicable).
We POST this body to the endpoint you registered for subscription.cancelled.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.cancelled"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.cancelled",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription activated
subscription.activatedSent when a subscription enters ACTIVE state.
We POST this body to the endpoint you registered for subscription.activated.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.activated"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredCurrent subscription in ACTIVE state.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.activated",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription renewed
subscription.renewedSent when a subscription successfully renews into a new billing period/term.
We POST this body to the endpoint you registered for subscription.renewed.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.renewed"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at start of new term/period.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.renewed",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription ended
subscription.endedSent when a subscription reaches its final end (no longer billable / usable).
We POST this body to the endpoint you registered for subscription.ended.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.ended"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredFinal subscription state.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.ended",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}Subscription subscriber set
subscription.subscriber_setSent when a subscriber is assigned to a subscription.
We POST this body to the endpoint you registered for subscription.subscriber_set.
Payloadrequiredapplication/json
The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:
a stable event identifier for deduplication, the event type to dispatch on, when the change
happened, and the event-specific payload in data.
eventstringuuidrequiredUnique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.
typeconst "subscription.subscriber_set"requiredoccurredstringdate-timerequiredRFC 3339 timestamp when the underlying change occurred.
dataobjectrequiredSubscription snapshot at the time of this event.
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe 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.
displaystringrequiredHuman-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.
msisdnstringphonerequiredThe 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.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe 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.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailThe subscriber's email address, if one has been provided.
addressobjectThe 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.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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.
Show child attributes
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectA 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.
Show child attributes
msisdnstringphonerequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
pendingobjectA 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.
Show child attributes
statusenum<string>requiredCurrent 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
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA 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.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringrequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent 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
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe 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.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringAcknowledgement
200Acknowledged
Acknowledged
Acknowledged
4XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
5XXTemporary failure - will retry
Temporary failure - will retry
Temporary failure - will retry
{
"eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
"type": "subscription.subscriber_set",
"occurredAt": "2024-01-15T10:30:00Z",
"data": {
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street1": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"discount": 9.99,
"discountMinor": 1,
"netPrice": 29.99,
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "ONE_TIME",
"boundMonths": 12,
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
}
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptions": {
"propertyName": 9.99
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}
}