Schemas
Every request, response and webhook payload schema in the API.
AddLineItemRequest
Request to add a line item to an order.
lineone ofrequiredA line item in an order representing a billable action or service.
Show child attributes
Selected by type.
activatebooleanWhether the subscription waits for the subscriber to activate it rather than being activated on a date.
The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.
Cannot be combined with scheduleActivationAt.
displaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
leasestringToken received when leasing a number. Required when an msisdn is provided from the number pool.
linestringrequiredUnique identifier for this line item within the order.
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
msisdnstringpersonal dataThe phone number for this subscription.
- Leave empty to have one assigned.
- When the number pool is available, you can choose a number from the pool and provide the leaseToken.
- When porting a number, provide the number and porting details.
portingobjectDetails needed to port in a number for this subscription.
Show child attributes
portingbooleanIf true, the number is a port-in.
productstringrequiredThe product offering to create a subscription for.
schedulestringdateDate when the subscription should be activated. Cannot be combined with activateOnDemand.
simobjectThe choice between eSIM and physical SIM plus related device details.
This value is optional while the order is a draft. You must give it before you submit the order.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriberobjectThe person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.
Show child attributes
tempbooleanWhether to use a temporary number until the porting is completed.
If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.
Can only be used when porting in a number (i.e., when msisdn and porting details are provided).
typeenum<string>requiredIdentifies this line item as a new subscription purchase. Always SUBSCRIPTION.
values
SUBSCRIPTION
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent subscription line item in this same order.
Either this or subscriptionId must be provided.
productstringrequiredThe add-on product offering to add.
scheduledstringdateWhen to activate the add-on.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringAn existing subscription to add the add-on to.
Either this or parentLineItemId must be provided.
typeenum<string>requiredIdentifies this line item as adding an add-on to a subscription. Always ADDON.
values
ADDON
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent line item in this order.
productstringrequiredThe external product offering from the catalog.
quantityinteger>= 1Quantity of the external product.
schedulestringdateDate when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
typeenum<string>requiredIdentifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.
values
EXTERNAL_PRODUCT
descriptionstringDescription of the external item.
fulfillmentstringuriOptional webhook URL for fulfillment notifications.
linestringrequiredUnique identifier for this line item within the order.
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
namestringrequiredName of the external item.
parentstringReference to parent line item in this order.
priceobjectrequiredCustom pricing for the external item.
Show child attributes
quantityinteger>= 1Quantity of the external item.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
taxationstringUS taxation ID for tax calculation.
typeenum<string>requiredIdentifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.
values
EXTERNAL
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.
The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.
values
PLAN_CHANGESIM_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of a subscription.
Show child attributes
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
simobjectThe SIM card change. Give this value only for changeType SIM_CHANGE.
A change of the SIM card of a subscription. The change carries a one-time price.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe identifier of the existing subscription that this line item changes.
typeenum<string>requiredIdentifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.
values
SUBSCRIPTION_CHANGE
addonstringrequiredThe identifier of the existing add-on on the subscription that this line item changes.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the add-on.
values
PLAN_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of an add-on.
Show child attributes
reasonstringFree-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe subscription containing the add-on to modify.
typeenum<string>requiredIdentifies this line item as a change to an existing add-on. Always ADDON_CHANGE.
values
ADDON_CHANGE
{
"lineItem": {
"activateOnDemand": true,
"display": "John Doe - Work phone",
"extensions": {
"propertyName": "string"
},
"leaseToken": "lease_8f3b1c2d4e5f6789",
"lineItemId": "line-item-1",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"porting": {
"details": {
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}
},
"portingRequested": true,
"productOfferingId": "mobile-plan-basic",
"scheduleActivationAt": "2024-02-01",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"name": "John Doe"
},
"tempNumber": true,
"type": "SUBSCRIPTION"
}
}AddonChangeLineItem
Line item that changes an add-on of a subscription.
The changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item.
addonstringrequiredThe identifier of the existing add-on on the subscription that this line item changes.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the add-on.
values
PLAN_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
*stringplanobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of an add-on.
Show child attributes
productstringrequiredThe add-on offering to change to.
reasonstringFree-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe subscription containing the add-on to modify.
typeenum<string>requiredIdentifies this line item as a change to an existing add-on. Always ADDON_CHANGE.
values
ADDON_CHANGE
{
"addonId": "addon-123",
"changeType": "PLAN_CHANGE",
"lineItemId": "line-item-9",
"metadata": {
"propertyName": "string"
},
"planChange": {
"productOfferingId": "addon-data-5gb"
},
"reason": "Customer upgrade request",
"scheduleDate": "2024-02-01",
"status": "PENDING",
"subscriptionId": "subscription-456",
"type": "ADDON_CHANGE"
}AddonLineItem
Line item for adding an add-on to a subscription.
linestringrequiredUnique identifier for this line item within the order.
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
*stringparentstringReference to parent subscription line item in this same order.
Either this or subscriptionId must be provided.
productstringrequiredThe add-on product offering to add.
scheduledstringdateWhen to activate the add-on.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringAn existing subscription to add the add-on to.
Either this or parentLineItemId must be provided.
typeenum<string>requiredIdentifies this line item as adding an add-on to a subscription. Always ADDON.
values
ADDON
{
"lineItemId": "line-item-3",
"metadata": {
"propertyName": "string"
},
"parentLineItemId": "line-item-1",
"productOfferingId": "addon-data-5gb",
"scheduledAt": "2024-02-01",
"status": "PENDING",
"subscriptionId": "subscription-456",
"type": "ADDON"
}AddonPlanChange
A change of the product of an add-on.
productstringrequiredThe add-on offering to change to.
{
"productOfferingId": "addon-data-5gb"
}Address
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
{
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}AddressValidationResult
Result of address validation with optional suggestions.
Depending on setup, address validation is either shape based (e.g. this looks like an address), or verified against an address registry.
suggestedobjectIf provided, a suggestion for a corrected address by the underlying address validation service.
Do note that this may be returned for seemingly valid addresses, where the network has a more precise or standardized version of the address. A typical example of this is the address is found in the networks' registry but under a different name because it contains aliases or minor formatting issues, mistyped zip codes, etc.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
validbooleanrequiredWhether the provided address is valid.
validationobjectAdditional validation details.
Show child attributes
issuesarray of objectSpecific issues found with the address.
Show child attributes
messagestringrequiredDescription of the issue found.
propertystringThe property or field related to the issue (e.g., "street", "zipCode").
{
"suggestedAddress": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"valid": false,
"validationDetails": {
"issues": [
{
"message": "Missing city",
"property": "city"
},
{
"message": "Invalid zip format",
"property": "zip"
}
]
}
}Any
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
propertyanyAny additional properties, passed through as given.
"string"BarReason
Why a subscription is barred. The reason tells what removes the bar.
- UNKNOWN: The bar has no recorded reason.
- NEW_SIM_CARD: The SIM card is blocked, for example after a lost or stolen phone. A new SIM card removes the bar.
- MISSING_PAYMENT: A payment is missing. The payment removes the bar.
- FRAUD: The fraud check barred the subscription.
- CUSTOMER_BLOCKED: The customer of the subscription is blocked. An unblock of the customer removes the bar.
- MANUAL: An operator barred the subscription by hand.
ExampleMISSING_PAYMENT
values
UNKNOWNNEW_SIM_CARDMISSING_PAYMENTFRAUDCUSTOMER_BLOCKEDMANUAL
"MISSING_PAYMENT"BillingCycle
How often a recurring price is charged.
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
{
"interval": 1,
"period": "MONTHLY"
}BindingContract
A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
durationobjectrequiredA length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
{
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
}BroadbandFacts
The values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price.
additionalnumberrequiredThe amount of data, in GB, that overUsageDataPriceMinor buys. Always 0, because the platform sells no data after the allowance.
earlyintegerint64requiredThe fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee.
monthlyarray of BroadbandFactsFeerequiredThe fees that the provider adds to the monthly price.
Show child attributes
amountintegerint64requiredThe amount of the fee, in minor currency units.
namestringrequiredWhat the label calls the fee.
overintegerint64requiredThe price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price.
planstringrequired15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan
identifier on the label is M, then the FCC Registration Number of the brand, then this code.
singlearray of BroadbandFactsFeerequiredThe fees that the customer pays one time, when they buy the plan.
Show child attributes
amountintegerint64requiredThe amount of the fee, in minor currency units.
namestringrequiredWhat the label calls the fee.
unlimitedbooleanrequiredTrue when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product.
{
"additionalDataIncrementGb": 0,
"earlyTerminationFeeMinor": 0,
"monthlyProviderFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"overUsageDataPriceMinor": 0,
"planCode": "FLEXSTANDARD001",
"singlePurchaseFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"unlimitedData": false
}BroadbandFactsFee
One fee on the FCC Broadband Facts label.
amountintegerint64requiredThe amount of the fee, in minor currency units.
namestringrequiredWhat the label calls the fee.
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}CancelPaymentSessionRequest
Request to cancel an active payment session.
metadataobject with string keysCustom key-value pairs for additional cancellation information.
Show child attributes
*stringreasonstringOptional reason for cancelling the payment session.
{
"metadata": {
"cancelled_by": "customer_service",
"ticket_id": "SUPP-12345"
},
"reason": "Customer changed their mind"
}ChangeSubscriptionServiceAddressRequest
Request to change the address where a subscription is served.
addressobjectrequiredThe address where the subscriber uses this subscription.
An address that is equal to the billing address of the customer removes the address that the subscription holds. The subscription then takes the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}
}CheckNetworkCoverageRequest
Request to check network coverage at a location.
addressobjectrequiredA location to check network coverage at.
Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it.
Show child attributes
citystringThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').
{
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}
}CheckPortingEligibilityRequest
Request to check if a phone number is eligible for porting.
msisdnstringphonepersonal datarequiredThe phone number to check for porting eligibility.
{
"msisdn": "+15551234567"
}Consents
The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later.
*string{
"marketing": "true",
"termsOfService": "true"
}Coordinates
A geographic location in WGS84 coordinates, the standard used by GPS.
latitudenumberfloatpersonal datarequiredLatitude in decimal degrees. Positive values are north of the equator.
longitudenumberfloatpersonal datarequiredLongitude in decimal degrees. Negative values are west of the prime meridian.
{
"latitude": 40.7128,
"longitude": -74.006
}CoverageAddress
A location to check network coverage at.
Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it.
citystringThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').
{
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}CreateOrderRequest
Request to create a new order for a customer of the user that makes the request. You can create an order with the minimum data, then add the remainder of the data in subsequent requests.
The bearer token supplies the user, so the request gives no user. A user can manage more than one customer, so the request names the customer that the order is for.
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
addressobjectThe billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.
The platform reads it for tax only when the customer holds no billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataBilling contact email.
namestringBilling contact name.
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
*stringcustomerone ofReference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer.
Show child attributes
customerstringrequiredThe customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.
authenticatedbooleanrequiredAlways true.
billingobjectBilling configuration and payment preferences for the new customer.
Show child attributes
contactobjectContact information for the new customer.
Show child attributes
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
identitystringpersonal dataA 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.
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
namestringrequiredName for the new customer.
preferredstringPreferred locale for the customer.
referencestringmax length 255Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.
customerenum<string>requiredThe type of customer this order is for. This scopes the order to the customer type's context, which affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it.
For logged in orders, this must match the customer's type.
values
CONSUMERBUSINESS
linearray of OrderLineItemInitial line items for the order (can be empty).
Show child attributes
Selected by type.
activatebooleanWhether the subscription waits for the subscriber to activate it rather than being activated on a date.
The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.
Cannot be combined with scheduleActivationAt.
displaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
leasestringToken received when leasing a number. Required when an msisdn is provided from the number pool.
linestringrequiredUnique identifier for this line item within the order.
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
msisdnstringpersonal dataThe phone number for this subscription.
- Leave empty to have one assigned.
- When the number pool is available, you can choose a number from the pool and provide the leaseToken.
- When porting a number, provide the number and porting details.
portingobjectDetails needed to port in a number for this subscription.
Show child attributes
portingbooleanIf true, the number is a port-in.
productstringrequiredThe product offering to create a subscription for.
schedulestringdateDate when the subscription should be activated. Cannot be combined with activateOnDemand.
simobjectThe choice between eSIM and physical SIM plus related device details.
This value is optional while the order is a draft. You must give it before you submit the order.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriberobjectThe person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.
Show child attributes
tempbooleanWhether to use a temporary number until the porting is completed.
If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.
Can only be used when porting in a number (i.e., when msisdn and porting details are provided).
typeenum<string>requiredIdentifies this line item as a new subscription purchase. Always SUBSCRIPTION.
values
SUBSCRIPTION
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent subscription line item in this same order.
Either this or subscriptionId must be provided.
productstringrequiredThe add-on product offering to add.
scheduledstringdateWhen to activate the add-on.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringAn existing subscription to add the add-on to.
Either this or parentLineItemId must be provided.
typeenum<string>requiredIdentifies this line item as adding an add-on to a subscription. Always ADDON.
values
ADDON
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent line item in this order.
productstringrequiredThe external product offering from the catalog.
quantityinteger>= 1Quantity of the external product.
schedulestringdateDate when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
typeenum<string>requiredIdentifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.
values
EXTERNAL_PRODUCT
descriptionstringDescription of the external item.
fulfillmentstringuriOptional webhook URL for fulfillment notifications.
linestringrequiredUnique identifier for this line item within the order.
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
namestringrequiredName of the external item.
parentstringReference to parent line item in this order.
priceobjectrequiredCustom pricing for the external item.
Show child attributes
quantityinteger>= 1Quantity of the external item.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
taxationstringUS taxation ID for tax calculation.
typeenum<string>requiredIdentifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.
values
EXTERNAL
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.
The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.
values
PLAN_CHANGESIM_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of a subscription.
Show child attributes
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
simobjectThe SIM card change. Give this value only for changeType SIM_CHANGE.
A change of the SIM card of a subscription. The change carries a one-time price.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe identifier of the existing subscription that this line item changes.
typeenum<string>requiredIdentifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.
values
SUBSCRIPTION_CHANGE
addonstringrequiredThe identifier of the existing add-on on the subscription that this line item changes.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the add-on.
values
PLAN_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of an add-on.
Show child attributes
reasonstringFree-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe subscription containing the add-on to modify.
typeenum<string>requiredIdentifies this line item as a change to an existing add-on. Always ADDON_CHANGE.
values
ADDON_CHANGE
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
*stringpromostringPromo code to apply to the order. Rejected with internalCode 4119 when no promotion has
that code, or when it is outside its validity period.
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "billing@example.com",
"name": "John Doe"
},
"consents": {
"marketing": "true",
"termsOfService": "true"
},
"customer": {
"customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"customerType": "CONSUMER",
"lineItems": [
{
"activateOnDemand": true,
"display": "John Doe - Work phone",
"extensions": {
"propertyName": "string"
},
"leaseToken": "lease_8f3b1c2d4e5f6789",
"lineItemId": "line-item-1",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"porting": {
"details": {
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}
},
"portingRequested": true,
"productOfferingId": "mobile-plan-basic",
"scheduleActivationAt": "2024-02-01",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"name": "John Doe"
},
"tempNumber": true,
"type": "SUBSCRIPTION"
}
],
"metadata": {
"propertyName": "string"
},
"promoCode": "SUMMER2023",
"shipping": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
}
}CreatePaymentSessionRequest
Request to create a new payment session for processing payment for an order.
brandingobjectThe colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form.
Show child attributes
backgroundstringpattern ^#[0-9a-fA-F]{6}$The background color of the payment form, as a hex value with a leading number sign.
borderenum<string>The shape of the buttons and the input fields of the payment form.
values
PILLRECTANGULARROUNDED
buttonstringpattern ^#[0-9a-fA-F]{6}$The color of the payment button, as a hex value with a leading number sign.
displaystringmax length 100The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms.
cancelstringThe URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only.
grantbooleanWhether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.
hostedbooleanWhether to collect the payment on a hosted page. A hosted session returns hostedUrl, and you send the customer to it. An embedded session (false) returns providerContext, and you show the payment form inside your own checkout page. Defaults to true.
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
*stringorderstringrequiredThe unique identifier of the order to create a payment session for.
paymentstringA previously saved payment method to prefill on the payment page, for returning customers.
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
returnstringrequiredThe URL the customer comes back to after they pay. A hosted page redirects to it. An embedded form redirects to it only for a payment method that leaves the page, such as 3D Secure. Must be provided to create a session.
savebooleanWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
setbooleanWhether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.
{
"branding": {
"backgroundColor": "#ffffff",
"borderStyle": "PILL",
"buttonColor": "#0cf68c",
"displayName": "Seamless"
},
"cancelUrl": "https://example.com/order/checkout",
"grantAutopayConsent": false,
"hosted": true,
"metadata": {
"propertyName": "string"
},
"orderId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
"paymentProfileId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true,
"setAsDefaultPaymentProfile": false
}Currency
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
ExampleUSD
"USD"Customer
A customer is a billable entity, the person or organization responsible for paying for services.
The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
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.
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
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
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
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
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
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
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
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
humanstringA human-readable identifier for the customer that customers can state in support requests.
identitystringpersonal dataA 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.
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
*stringnamestringrequiredThe 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.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
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.
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
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
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
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"autoPay": true,
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"email": "billing@company.com",
"method": "E_INVOICE"
},
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"contactPerson": {
"name": "John Doe",
"role": "MEMBER",
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
},
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"deliveryAddress": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"humanReadableId": "29A-BY3Z-X78",
"identity": "12-3456789",
"metadata": {
"propertyName": "string"
},
"name": "John Doe",
"preferredLocale": "en-US",
"referenceId": "crm-customer-12345",
"shipping": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
},
"shippingAddress": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"users": [
{
"name": "John Doe",
"role": "MEMBER",
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
}
]
}CustomerBillingMethod
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
"E_INVOICE"CustomerType
Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
"CONSUMER"DeviceInfo
Information about a device based on its IMEI.
esimbooleanrequiredWhether the device supports eSIM.
imeistringpersonal datarequiredThe device IMEI that was checked.
manufacturerstringDevice manufacturer.
marketingstringDevice marketing name.
modelstringDevice model.
tacstringThe device TAC (Type Allocation Code), which is the first 8 digits of the IMEI identifying the device model and manufacturer.
{
"esim": true,
"imei": "356938035643809",
"manufacturer": "Apple",
"marketingName": "iPhone 15 Pro",
"model": "A2653",
"tac": "35693803"
}DeviceMatch
A device the network knows by name. It carries no IMEI, because a name matches a model rather than one handset.
esimbooleanrequiredWhether the device supports eSIM.
manufacturerstringDevice manufacturer.
marketingstringDevice marketing name.
modelstringDevice model.
tacstringThe device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.
{
"esim": true,
"manufacturer": "Apple",
"marketingName": "iPhone 15 Pro",
"model": "A2653",
"tac": "35693803"
}DeviceSearchResult
The devices whose name matches the query.
itemsarray of DeviceMatchrequiredOne entry per matching device. An empty list means the network knows no device by that name.
Show child attributes
esimbooleanrequiredWhether the device supports eSIM.
manufacturerstringDevice manufacturer.
marketingstringDevice marketing name.
modelstringDevice model.
tacstringThe device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.
{
"items": [
{
"esim": true,
"manufacturer": "Apple",
"marketingName": "iPhone 15 Pro",
"model": "A2653",
"tac": "35693803"
}
]
}Duration
A length of time, expressed as a count of some unit.
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
{
"unit": "MONTHS",
"value": 3
}EmbeddedAssignedTo
The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.
subscriptionstringDisplay name for the subscription (typically the phone number)
subscriptionstringrequiredThe unique identifier for the subscription
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
{
"subscriptionDisplay": "+1 (555) 123-4567",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"type": "SUBSCRIPTION"
}EmbeddedCustomer
Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
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.
{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
}EmbeddedCustomerUser
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
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
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
{
"name": "John Doe",
"role": "MEMBER",
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
}EmbeddedLicense
Essential license information without sensitive details.
activatedstringdate-timeWhen the license was activated.
assignedobjectrequiredThe entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.
Show child attributes
subscriptionstringDisplay name for the subscription (typically the phone number)
subscriptionstringrequiredThe unique identifier for the subscription
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
customerobjectCustomer 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.
licensestringrequiredThe unique identifier for the license.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
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
typestringThe 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.
{
"activatedAt": "2024-01-15T10:30:00Z",
"assignedTo": {
"subscriptionDisplay": "+1 (555) 123-4567",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"type": "SUBSCRIPTION"
},
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"status": "PENDING",
"type": "PBX_USER_LEVEL"
}EmbeddedPorting
Number porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
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
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
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
{
"direction": "INBOUND",
"msisdn": "+15551234567",
"scheduledAt": "2024-02-01",
"status": "PENDING"
}EmbeddedProduct
Embedded representation of a product.
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
featuresobjectThe features included with the product, if any. Typically used for telecom products.
Show child attributes
activationenum<string>How the travel eSIM package activates.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
values
INSTANTFIRST_USE
countriesarray of stringISO 3166-1 alpha-3 country codes where the product provides coverage.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
Use the countries query parameter on list endpoints to filter by coverage.
datanumberMegabytes of data included with the product. Present for cellular, data, and travel eSIM products.
includedintegerOutbound call seconds included with the product. Present for cellular subscription categories.
includedintegerNumber of SMS messages included with the product. Present for cellular subscription categories.
regionsarray of stringNamed regions covered by the product.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
Use the regions query parameter on list endpoints to filter by coverage.
simenum<string>The SIM format for a SIM card product.
values
PSIMESIM
validityintegerNumber of days the product is valid for.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
internalstringrequiredThe name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.
networkstringThe unique identifier for the network provider.
productstringrequiredThe unique identifier for the product.
typeenum<string>requiredThe type of product offering determines how it can be used and what kind of resource it creates.
SUBSCRIPTION Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).
- Includes categories like
SUBSCRIPTION_CELL,TRAVEL_ESIM - Can be created via order or directly depending on configuration
- Has its own lifecycle (activation, suspension, termination)
SUBSCRIPTION_ADDON Adds features or resources to an existing subscription.
- Includes categories like
TRAVEL_ESIM_PACKAGE - Must be attached to a parent subscription
LICENSE Creates a license for business/PBX features.
- Typically used for enterprise telephony features
EXTERNAL_PRODUCT Represents purchasable items outside the core telecom platform.
- Can only be ordered via orders, not created directly
SIM_CARD Replaces the SIM card for an existing subscription through a subscription change order.
values
SUBSCRIPTIONSUBSCRIPTION_ADDONLICENSEEXTERNAL_PRODUCTSIM_CARD
{
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"features": {
"activationType": "INSTANT",
"countries": [
"USA",
"CAN",
"MEX"
],
"dataMb": 2048,
"includedCallSeconds": 1000,
"includedSms": 500,
"regions": [
"NORTH_AMERICA"
],
"simCardType": "PSIM",
"validityDays": 30
},
"internalName": "us-mobile-unlimited-5gb",
"networkProviderId": "tmobile-us",
"productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
"type": "SUBSCRIPTION"
}EmbeddedProductOffering
Essential information about a product offering — what is being sold and at what price — without the full catalog details.
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
durationobjectrequiredA length of time, expressed as a count of some unit.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
*integerint64customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingintegerrequiredHow many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
{
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}EmbeddedSubscriber
The person who uses the service on a subscription, as distinct from the customer who pays for it.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
createdstringdate-timeDate and time when the subscriber was created.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
namestringrequiredThe subscriber's full name.
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
updatedstringdate-timeDate and time when the subscriber was last updated.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"createdAt": "2024-01-15T10:30:00Z",
"email": "john.doe@example.com",
"name": "John Doe",
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"updatedAt": "2024-01-20T14:45:00Z"
}Error
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
{
"code": "not_found",
"details": [
{
"code": "invalid_argument",
"message": "Email format is invalid.",
"property": "contact.email",
"reason": "property_invalid",
"suggestion": "string"
}
],
"domain": "address",
"externalCode": "3077",
"externalSource": "Tele2",
"hint": "Verify the customerId and try again.",
"internalCode": "4009",
"message": "The requested customer could not be found.",
"reason": "address_not_taxable",
"retryable": false,
"spanId": "37cec694d3b99f0f",
"traceId": "cc4a73acca1bb07e0e54bd41f5ce1e7e"
}EsimInstallationStatus
The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.
values
AVAILABLEALLOCATEDLINKEDCONFIRMEDRELEASEDDOWNLOADEDINSTALLEDENABLEDDISABLEDERRORUNAVAILABLEDELETED
"AVAILABLE"EsimQrCode
eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL.
expiresstringdate-timeWhen the QR code and any hosted URL expire. After this time, a new QR code should be requested. Omitted when no expiry applies.
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
*stringqrstringrequiredThe QR code data string that contains the eSIM profile download information (LPA format).
qrstringuriHosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead.
subscriptionstringrequiredThe unique identifier of the subscription this QR code belongs to.
{
"expiresAt": "2024-12-31T23:59:59Z",
"metadata": {
"propertyName": "string"
},
"qrCodeData": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012",
"qrCodeUrl": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
}ExternalLineItem
Line item for selling an externally managed product or service that is not in the product catalog. You define the name, price, and taxation, and can optionally receive a webhook to fulfill the item yourself.
descriptionstringDescription of the external item.
fulfillmentstringuriOptional webhook URL for fulfillment notifications.
linestringrequiredUnique identifier for this line item within the order.
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
*stringnamestringrequiredName of the external item.
parentstringReference to parent line item in this order.
priceobjectrequiredCustom pricing for the external item.
Show child attributes
amountintegerint64requiredThe price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD).
currencystringrequiredThe ISO 4217 currency code the price is expressed in. Must match the order currency.
quantityinteger>= 1Quantity of the external item.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
taxationstringUS taxation ID for tax calculation.
typeenum<string>requiredIdentifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.
values
EXTERNAL
{
"description": "Professional on-site installation and setup",
"fulfillmentWebhook": "https://partner.com/webhooks/fulfillment",
"lineItemId": "line-item-6",
"metadata": {
"propertyName": "string"
},
"name": "Custom Installation Service",
"parentLineItemId": "line-item-1",
"price": {
"amountMinor": 9999,
"currency": "USD"
},
"quantity": 1,
"status": "PENDING",
"taxationId": "TAX123456",
"type": "EXTERNAL"
}ExternalProductLineItem
Line item for purchasing a catalog product that is fulfilled outside the platform. The order records the sale while fulfillment happens in your own systems.
linestringrequiredUnique identifier for this line item within the order.
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
*stringparentstringReference to parent line item in this order.
productstringrequiredThe external product offering from the catalog.
quantityinteger>= 1Quantity of the external product.
schedulestringdateDate when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
typeenum<string>requiredIdentifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.
values
EXTERNAL_PRODUCT
{
"lineItemId": "line-item-5",
"metadata": {
"propertyName": "string"
},
"parentLineItemId": "line-item-1",
"productOfferingId": "external-device-iphone15",
"quantity": 2,
"scheduleActivationAt": "2024-02-01",
"status": "PENDING",
"type": "EXTERNAL_PRODUCT"
}GetDeviceInfoRequest
Request to get device information by IMEI.
imeistringpersonal datarequiredThe International Mobile Equipment Identity of the device.
{
"imei": "356938035643809"
}Identity
A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
Example12-3456789
"12-3456789"InlineValidationError
A single validation problem reported on an entity, explaining what must be corrected. For example, orders return these for anything that blocks submission.
codeenum<string>deprecatedDeprecated. Use reason.
A code for the problem. An order sets it when the order cannot buy the product offering of a line item:
- NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer.
- ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on.
- OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering.
A problem without a code is a field that is missing or not correct.
values
NOT_AN_INITIAL_OFFERINGADDON_NOT_APPLICABLEOFFERING_CHANGE_NOT_AVAILABLE
messagestringrequiredValidation error message.
propertystringProperty related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").
reasonstringNames the problem. property_required is a missing value, property_invalid is a value with
the wrong format, and property_conflict is two values that cannot occur together. Other
reasons name a business condition, for example not_an_initial_offering. Your client must
accept a reason that it does not know.
{
"code": "NOT_AN_INITIAL_OFFERING",
"message": "Subscriber name is required.",
"property": "subscriber.name",
"reason": "not_an_initial_offering"
}Invoice
An invoice used to collect a payment from a customer. The invoice records the provider's invoice lifecycle and balances; the related payment intent records what is being collected, its payment attempts, and any refunds.
subtotalintegerint64deprecatedDeprecated. Read the related payment intent's line items instead.
taxintegerint64deprecatedDeprecated. Read the related payment intent's line-item taxes instead.
feeintegerint64deprecatedDeprecated. The invoice projection has no separate fee total.
discountintegerint64deprecatedDeprecated. Read the related payment intent's line-item discounts instead.
totalintegerint64deprecatedDeprecated. Read amountDueMinor instead.
amountintegerint64requiredThe amount due when the invoice was issued, in minor units of the invoice currency.
amountintegerint64requiredThe amount credited to the invoice, in minor units of the invoice currency.
amountintegerint64requiredThe amount still unpaid, in minor units of the invoice currency.
createdstringdate-timerequiredWhen the invoice record was created.
currencystringrequiredThe ISO 4217 currency code for the invoice amounts.
customerstringrequiredThe customer this invoice collects payment from.
duestringdaterequiredThe date payment is due. Absent when the provider has no due date.
hostedstringuriThe provider-hosted page where the customer can view and pay the invoice.
invoicestringrequiredUnique identifier for the invoice.
issuedstringdate-timeWhen the provider issued the invoice. Absent while the invoice is a draft.
numberstringThe provider's human-readable invoice number or payment reference. Absent until the provider assigns one.
sentstringdate-timedeprecatedDeprecated. Read issuedAt instead.
paidstringdate-timeWhen the invoice became paid.
paymentobjectThe payment intent associated with this invoice, including payment attempts and refunds. This field is absent for invoices that do not have a related payment intent.
The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items.
A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice.
Show child attributes
amountintegerint64requiredThe total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
attemptsarray of PaymentAttemptrequiredCharge attempts made against this payment intent, most recent first.
Show child attributes
amountintegerint64requiredThe amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
chargedstringdate-timeWhen the charge was made.
createdstringdate-timerequiredWhen the attempt was created.
currencystringrequiredThe ISO 4217 currency code the attempt was charged in (e.g., "USD").
paymentstringrequiredThe unique identifier for this charge attempt.
reasonstringFailure reason when the attempt did not succeed.
resultenum<string>requiredWhether the charge attempt succeeded or failed.
values
SUCCEEDEDFAILED
createdstringdate-timerequiredWhen the payment intent was created.
currencystringrequiredThe ISO 4217 currency code the amount is collected in (e.g., "USD").
customerstringrequiredThe customer this payment intent collects from.
descriptionstringA human-readable description of what is being collected.
discountsarray of PaymentIntentDiscountrequiredReductions applied to the payment intent as a whole rather than to one billed line.
Show child attributes
amountintegerint64requiredThe positive amount deducted, in minor units of the payment intent currency.
descriptionstringrequiredWhy the payment intent was reduced.
duestringdate-timeWhen the amount is due.
linearray of PaymentIntentLineItemrequiredThe items that make up the collected amount.
Show child attributes
amountintegerint64requiredThe base cost of the line item before discounts, in minor units of the payment intent's
currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless
includesTax is true and they are a part of it.
descriptionstringrequiredWhat this line item represents.
discountsarray of objectDiscounts applied to this line item.
Show child attributes
includesbooleanWhether the taxes are a part of amountMinor rather than added to it.
licensestringThe license this line item is associated with, if any.
subscriptionstringThe subscription this line item is associated with, if any.
taxesarray of objectTaxes applied to this line item.
Show child attributes
paymentstringrequiredThe unique identifier for this payment intent.
refundsarray of PaymentRefundrequiredRefunds issued against this payment intent.
Show child attributes
amountintegerint64requiredThe refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
createdstringdate-timerequiredWhen the refund was created.
currencystringrequiredThe ISO 4217 currency code the refund is issued in (e.g., "USD").
reasonenum<string>Why the refund was issued.
values
UNKNOWNDUPLICATEFRAUDULENTREQUESTED_BY_CUSTOMERDISPUTE_LOST
refundstringrequiredThe unique identifier for this refund.
statusenum<string>requiredCurrent stage of the refund.
values
PENDINGSUCCEEDEDFAILEDCANCELEDREQUIRES_ACTION
statusenum<string>requiredCurrent stage of a payment intent as it is collected through the payment provider.
- UNKNOWN: The platform has no supported mapping for the current provider state.
- PENDING: Created, no charge attempted yet.
- REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
- PROCESSING: A charge is in flight with the payment provider.
- SUCCEEDED: The full amount has been collected.
- REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
- CANCELED: Collection was canceled and no further charges will be attempted.
values
UNKNOWNPENDINGREQUIRES_ACTIONPROCESSINGSUCCEEDEDREQUIRES_PAYMENT_METHODCANCELED
updatedstringdate-timerequiredWhen the payment intent was last updated.
paymentenum<string>The provider that issued and manages the invoice.
Payment service provider that processes the transaction.
values
STRIPEBILLOGRAM
invoicestringurideprecatedDeprecated. Read hostedUrl instead.
pdfstringuriDirect URL to the provider-generated invoice PDF.
linearray of InvoiceLineItemdeprecatedrequiredDeprecated. Read paymentIntent.lineItems instead.
Show child attributes
descriptionstringrequiredDescription of what this line item represents.
discountsarray of objectDetailed discount breakdown for this line item.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
feesarray of objectDetailed fee breakdown for this line item.
Show child attributes
amountintegerint64requiredFee amount, in minor currency units.
namestringrequiredFee name or description.
licensestringID of the license this line item is associated with, if applicable.
productstringID of the product offering this line item is associated with, if applicable.
quantityinteger>= 1Quantity of items for this line item.
subscriptionstringID of the subscription this line item is associated with, if applicable.
subtotalintegerint64requiredLine item subtotal (quantity x unitPriceMinor), in minor currency units.
taxintegerint64Total taxes for this line item, in minor currency units.
taxarray of TaxBreakdownItemTax breakdown for this line item.
Show child attributes
amountintegerint64requiredThe amount charged for this tax component, in minor units of the currency of the transaction.
descriptionstringrequiredHuman-readable name of the tax or fee, suitable for display on invoices and receipts.
ratenumberdecimalThe tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.
taxbooleanWhether taxes are included in the total.
totalintegerint64Total discounts for this line item, in minor currency units.
totalintegerint64Total fees for this line item, in minor currency units.
totalintegerint64requiredLine item total after taxes, fees, and discounts, in minor currency units.
unitintegerint64Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).
invoicestringdeprecatedrequiredDeprecated. Read number instead.
statusenum<string>requiredCurrent status of the invoice.
Current stage of the invoice lifecycle.
- UNKNOWN: The provider status could not be mapped.
- DRAFT: The invoice has not been issued.
- ISSUED: The provider issued the invoice and it is awaiting payment.
- SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
- PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
- PAID: The invoice has been paid.
- OVERDUE: The invoice is past its due date and remains unpaid.
- UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
- VOID: The invoice was canceled and is no longer collectible.
- CREDITED: The invoice was settled by credit.
values
UNKNOWNDRAFTISSUEDSENTPARTIALLY_PAIDPAIDOVERDUEUNCOLLECTIBLEVOIDCREDITED
updatedstringdate-timerequiredWhen the invoice record was last updated.
voidedstringdate-timeWhen the invoice was voided.
metadataobject with string keysdeprecatedDeprecated. Invoice metadata is not stored by the platform.
A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string{
"subtotalAmountMinor": 1,
"taxAmountMinor": 1,
"feeAmountMinor": 1,
"discountAmountMinor": 1,
"totalAmountMinor": 1,
"amountDueMinor": 3239,
"amountPaidMinor": 0,
"amountRemainingMinor": 3239,
"createdAt": "2026-08-01T08:00:00Z",
"currency": "USD",
"customerId": "456789ab-cdef-0123-4567-89abcdef0123",
"dueDate": "2026-08-31",
"hostedUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000",
"invoiceId": "123e4567-e89b-12d3-a456-426614174000",
"issuedAt": "2026-08-01T08:00:00Z",
"number": "INV-2026-001",
"sentAt": "2024-01-15T10:30:00Z",
"paidAt": "2026-08-20T14:30:00Z",
"paymentIntent": {
"amountMinor": 2900,
"attempts": [
{
"amountMinor": 2900,
"chargedAt": "2024-01-15T10:00:00Z",
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
"reason": "card_declined",
"result": "SUCCEEDED"
}
],
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"description": "Mobile subscription renewal",
"discounts": [
{
"amountMinor": 1000,
"description": "Goodwill credit"
}
],
"dueAt": "2024-01-15T10:00:00Z",
"lineItems": [
{
"amountMinor": 2900,
"description": "Mobile subscription - Premium Plan",
"discounts": [
{
"amountMinor": 500,
"description": "Loyalty discount"
}
],
"includesTax": false,
"licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
"subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
"taxes": [
{
"amountMinor": 725,
"description": "VAT 25%"
}
]
}
],
"paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
"refunds": [
{
"amountMinor": 2900,
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"reason": "REQUESTED_BY_CUSTOMER",
"refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
"status": "SUCCEEDED"
}
],
"status": "SUCCEEDED",
"updatedAt": "2024-01-15T10:00:00Z"
},
"paymentProvider": "STRIPE",
"invoiceUrl": "https://example.com/resource",
"pdfUrl": "https://example.com/invoices/123e4567-e89b-12d3-a456-426614174000.pdf",
"lineItems": [
{
"description": "Mobile subscription - Premium Plan",
"discounts": [
{
"amountMinor": 500,
"name": "Volume discount"
}
],
"fees": [
{
"amountMinor": 1000,
"name": "Late payment fee"
}
],
"licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
"productOfferingId": "mobile-plan-premium",
"quantity": 1,
"subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
"subtotalMinor": 2999,
"taxAmountMinor": 240,
"taxBreakdown": [
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}
],
"taxIncluded": false,
"totalDiscountsMinor": 500,
"totalFeesMinor": 1000,
"totalMinor": 3739,
"unitPriceMinor": 2999
}
],
"invoiceNumber": "string",
"status": "UNKNOWN",
"updatedAt": "2026-08-01T08:00:00Z",
"voidedAt": "2026-08-10T09:00:00Z",
"metadata": {
"propertyName": "string"
}
}InvoiceLineItem
Individual line item within an invoice, showing detailed pricing breakdown.
descriptionstringrequiredDescription of what this line item represents.
discountsarray of objectDetailed discount breakdown for this line item.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
feesarray of objectDetailed fee breakdown for this line item.
Show child attributes
amountintegerint64requiredFee amount, in minor currency units.
namestringrequiredFee name or description.
licensestringID of the license this line item is associated with, if applicable.
productstringID of the product offering this line item is associated with, if applicable.
quantityinteger>= 1Quantity of items for this line item.
subscriptionstringID of the subscription this line item is associated with, if applicable.
subtotalintegerint64requiredLine item subtotal (quantity x unitPriceMinor), in minor currency units.
taxintegerint64Total taxes for this line item, in minor currency units.
taxarray of TaxBreakdownItemTax breakdown for this line item.
Show child attributes
amountintegerint64requiredThe amount charged for this tax component, in minor units of the currency of the transaction.
descriptionstringrequiredHuman-readable name of the tax or fee, suitable for display on invoices and receipts.
ratenumberdecimalThe tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.
taxbooleanWhether taxes are included in the total.
totalintegerint64Total discounts for this line item, in minor currency units.
totalintegerint64Total fees for this line item, in minor currency units.
totalintegerint64requiredLine item total after taxes, fees, and discounts, in minor currency units.
unitintegerint64Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).
{
"description": "Mobile subscription - Premium Plan",
"discounts": [
{
"amountMinor": 500,
"name": "Volume discount"
}
],
"fees": [
{
"amountMinor": 1000,
"name": "Late payment fee"
}
],
"licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
"productOfferingId": "mobile-plan-premium",
"quantity": 1,
"subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
"subtotalMinor": 2999,
"taxAmountMinor": 240,
"taxBreakdown": [
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}
],
"taxIncluded": false,
"totalDiscountsMinor": 500,
"totalFeesMinor": 1000,
"totalMinor": 3739,
"unitPriceMinor": 2999
}InvoiceListItem
An invoice summary. Get the invoice to read its related payment intent, payment attempts, and refunds.
subtotalintegerint64deprecatedDeprecated. Get the invoice and read its related payment intent instead.
totalintegerint64deprecatedDeprecated. Read amountDueMinor instead.
amountintegerint64requiredThe amount due when the invoice was issued, in minor units of the invoice currency.
amountintegerint64requiredThe amount credited to the invoice, in minor units of the invoice currency.
amountintegerint64requiredThe amount still unpaid, in minor units of the invoice currency.
createdstringdate-timerequiredWhen the invoice record was created.
currencystringrequiredThe ISO 4217 currency code for the invoice amounts.
customerstringrequiredThe customer this invoice collects payment from.
duestringdaterequiredThe date payment is due. Absent when the provider has no due date.
hostedstringuriThe provider-hosted page where the customer can view and pay the invoice.
invoicestringrequiredUnique identifier for the invoice.
issuedstringdate-timeWhen the provider issued the invoice. Absent while the invoice is a draft.
numberstringThe provider's human-readable invoice number or payment reference. Absent until the provider assigns one.
sentstringdate-timedeprecatedDeprecated. Read issuedAt instead.
paidstringdate-timeWhen the invoice became paid.
paymentenum<string>The provider that issued and manages the invoice.
Payment service provider that processes the transaction.
values
STRIPEBILLOGRAM
invoicestringurideprecatedDeprecated. Read hostedUrl instead.
pdfstringuriDirect URL to the provider-generated invoice PDF.
invoicestringdeprecatedrequiredDeprecated. Read number instead.
statusenum<string>requiredCurrent status of the invoice.
Current stage of the invoice lifecycle.
- UNKNOWN: The provider status could not be mapped.
- DRAFT: The invoice has not been issued.
- ISSUED: The provider issued the invoice and it is awaiting payment.
- SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
- PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
- PAID: The invoice has been paid.
- OVERDUE: The invoice is past its due date and remains unpaid.
- UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
- VOID: The invoice was canceled and is no longer collectible.
- CREDITED: The invoice was settled by credit.
values
UNKNOWNDRAFTISSUEDSENTPARTIALLY_PAIDPAIDOVERDUEUNCOLLECTIBLEVOIDCREDITED
updatedstringdate-timerequiredWhen the invoice record was last updated.
voidedstringdate-timeWhen the invoice was voided.
metadataobject with string keysdeprecatedDeprecated. Invoice metadata is not stored by the platform.
A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string{
"subtotalAmountMinor": 1,
"totalAmountMinor": 1,
"amountDueMinor": 3239,
"amountPaidMinor": 0,
"amountRemainingMinor": 3239,
"createdAt": "2026-08-01T08:00:00Z",
"currency": "USD",
"customerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"dueDate": "2026-08-31",
"hostedUrl": "https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d",
"invoiceId": "094f10ca-616e-441c-b264-9a2305d6692d",
"issuedAt": "2026-08-01T08:00:00Z",
"number": "INV-2026-001",
"sentAt": "2024-01-15T10:30:00Z",
"paidAt": "2026-08-20T14:30:00Z",
"paymentProvider": "STRIPE",
"invoiceUrl": "https://example.com/resource",
"pdfUrl": "https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d.pdf",
"invoiceNumber": "string",
"status": "UNKNOWN",
"updatedAt": "2026-08-01T08:00:00Z",
"voidedAt": "2026-08-10T09:00:00Z",
"metadata": {
"propertyName": "string"
}
}InvoiceStatus
Current stage of the invoice lifecycle.
- UNKNOWN: The provider status could not be mapped.
- DRAFT: The invoice has not been issued.
- ISSUED: The provider issued the invoice and it is awaiting payment.
- SENT: Deprecated alias accepted in status filters. Responses use ISSUED.
- PARTIALLY_PAID: Some, but not all, of the amount due has been paid.
- PAID: The invoice has been paid.
- OVERDUE: The invoice is past its due date and remains unpaid.
- UNCOLLECTIBLE: The provider no longer expects to collect the invoice.
- VOID: The invoice was canceled and is no longer collectible.
- CREDITED: The invoice was settled by credit.
values
UNKNOWNDRAFTISSUEDSENTPARTIALLY_PAIDPAIDOVERDUEUNCOLLECTIBLEVOIDCREDITED
"UNKNOWN"License
A license represents a permission to use a software product with embedded customer and product offering details.
activatedstringdaterequiredThe date when the license was activated.
assignedobjectThe entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.
Show child attributes
subscriptionstringDisplay name for the subscription (typically the phone number)
subscriptionstringrequiredThe unique identifier for the subscription
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
cancelledstringdateThe date when the license was canceled (if applicable).
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.
detailsobjectAdditional license details specific to certain license types.
Show child attributes
propertyanyAny additional properties, passed through as given.
licensestringrequiredThe unique identifier for the license.
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
*stringpausedstringdateThe date when the license was paused (if applicable).
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
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
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
scheduledstringdaterequiredThe date when the pending status change is scheduled to occur.
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
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
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.
{
"activatedAt": "2024-01-15",
"assignedTo": {
"subscriptionDisplay": "+1 (555) 123-4567",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"type": "SUBSCRIPTION"
},
"cancelledAt": "2024-06-30",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"details": {},
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"metadata": {
"propertyName": "string"
},
"pausedAt": "2024-03-01",
"pendingProductOffering": {
"product": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"status": "PENDING",
"type": "PBX_USER_LEVEL"
}LicenseListItem
Simplified license representation optimized for list operations. The detailed License schema adds the customer and the product offering.
activatedstringdateThe date when the license was activated.
cancelledstringdateThe date when the license was canceled.
licensestringrequiredThe unique identifier for the license.
productstringrequiredThe unique identifier for the product offering that the license grants.
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
subscriptionstringThe subscription that the license is assigned to. Absent for a license that stands alone.
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.
{
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "PENDING",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "PBX_USER_LEVEL"
}LicenseStatus
Current stage of the license lifecycle.
- PENDING: Created but not yet activated
- ACTIVE: Active and billable; the licensed feature is available
- PAUSED: Temporarily stopped; the licensed feature is disabled
- CANCELLED: Permanently terminated
- BLOCKED: Disabled by the operator, typically for policy or payment reasons
values
PENDINGACTIVEPAUSEDCANCELLEDBLOCKED
"PENDING"LicenseType
The kind of feature the license unlocks. Most types cover business telephony (PBX) features,
such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client),
PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing
features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.
ExamplePBX_USER_LEVEL
"PBX_USER_LEVEL"LineItemSim
The choice between eSIM and physical SIM plus related device details.
esimbooleanrequiredWhether this line item uses eSIM technology.
iccidstringpersonal dataIntegrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.
This feature only applies to certain networks.
imeistringpersonal dataInternational Mobile Equipment Identity for eSIM activation.
Some networks require this to activate the eSIM.
{
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
}Metadata
A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
*string{
"propertyName": "string"
}NetworkCoverage
Network coverage information for a location.
Networks answer two different questions. One resolves the address to a point and grades the
signal there. Another qualifies a whole postal area for activation and grades nothing. Read
scope to know which answer you got, and read serviceable for the verdict itself.
What data is returned depends on the underlying network provider, so only the required fields are guaranteed to be present.
addressobjectrequiredThe address that was checked.
A location to check network coverage at.
Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it.
Show child attributes
citystringThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').
coordinatesobjectResolved coordinates for the address, if available.
A geographic location in WGS84 coordinates, the standard used by GPS.
Show child attributes
latitudenumberfloatpersonal datarequiredLatitude in decimal degrees. Positive values are north of the equator.
longitudenumberfloatpersonal datarequiredLongitude in decimal degrees. Negative values are west of the prime meridian.
coverageobject with string keysCoverage information per technology, if available.
Show child attributes
3gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
4gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
5gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
*objectCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
coverageenum<string>Overall network coverage quality at this location.
Absent when the network grades no signal. Do not read an absent grade as poor coverage:
read serviceable instead.
values
EXCELLENTGOODFAIRPOORNO_COVERAGE
networkstringWhich network this coverage data applies to.
roamingstringThe roaming status at this location, if reported by the network provider (e.g., whether the location is served by the home network or a roaming partner).
scopeenum<string>requiredWhat the verdict applies to.
ADDRESS means the network placed the exact address and answered about that point.
POSTAL_AREA means the network read the zip code alone, so the same answer applies to
every address in it.
values
ADDRESSPOSTAL_AREA
serviceablebooleanrequiredWhether the network serves this location. Every network answers this.
A network that grades signal reports true when at least one technology reaches the
location. A network that qualifies a postal area reports true when it can activate a
subscription there.
{
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"coordinates": {
"latitude": 40.7128,
"longitude": -74.006
},
"coverage": {
"3g": {
"available": true
},
"4g": {
"available": true
},
"5g": {
"available": true
},
"propertyName": {
"available": true
}
},
"coverageLevel": "GOOD",
"networkProviderId": "tmobile-us",
"roamingStatus": "HOME",
"scope": "ADDRESS",
"serviceable": true
}Order
A shopping cart for telecommunications services and products. Add line items to configure services, get pricing, and submit for fulfillment. Orders track progress from creation through completion.
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
addressobjectThe billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.
The platform reads it for tax only when the customer holds no billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataBilling contact email.
namestringBilling contact name.
completedstringdate-timeWhen the order was completed.
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
*stringcreatedstringdate-timerequiredWhen the order was created.
createdobjectEntities created as part of order fulfillment.
Show child attributes
addonsarray of anyAdd-ons created during order fulfillment.
Show child attributes
addedstringdate-timeThe date and time when the add-on was added to the subscription.
cancelledstringdate-timeThe date and time when the add-on was canceled (if applicable).
licensestringThe unique identifier of the license associated with this add-on (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
productstringThe unique identifier for the product offering group.
productstringrequiredThe unique identifier for the product offering.
referencestringmax length 255A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.
statusenum<string>requiredThe status of an add-on on a subscription.
- PENDING: Add-on is scheduled but not yet active
- ACTIVE: Add-on is currently active and billable
- CANCELLED: Add-on has been cancelled and is no longer active
- EXPIRED: Add-on has expired and is no longer active
values
PENDINGACTIVECANCELLEDEXPIRED
updatedstringdate-timeThe date and time when the add-on was last updated.
createdstringrequiredLine item ID that created this add-on.
licensesarray of anyStandalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.
Show child attributes
activatedstringdateThe date when the license was activated.
cancelledstringdateThe date when the license was canceled.
licensestringrequiredThe unique identifier for the license.
productstringrequiredThe unique identifier for the product offering that the license grants.
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
subscriptionstringThe subscription that the license is assigned to. Absent for a license that stands alone.
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.
createdstringrequiredLine item ID that created this license.
modificationsarray of anyModifications applied during order fulfillment.
Show child attributes
appliedstringdate-timeWhen the modification was applied.
newstringThe product offering the entity was changed to.
targetstringrequiredThe subscription or add-on that was modified.
typeenum<string>requiredType of modification applied.
values
SUBSCRIPTION_CHANGEADDON_CHANGE
createdstringrequiredLine item ID that created this modification.
subscriptionsarray of anySubscriptions created during order fulfillment.
Show child attributes
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.
customerstringrequiredThe unique identifier for the customer who owns this subscription.
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.
msisdnstringpersonal datarequiredThe 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.
productstringrequiredThe unique identifier for the product offering associated with this subscription.
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
subscriberstringrequiredThe unique identifier for the subscriber associated with this subscription.
subscriptionstringrequiredThe unique identifier for the subscription.
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.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
createdstringrequiredLine item ID that created this subscription.
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.
expiresstringdate-timerequiredWhen the order expires if not submitted (automatically refreshed on each order update to maintain active session).
externalobjectExternal payment details if the order was paid outside the system.
Show child attributes
receiptstringDescription of the external payment.
receiptstringuriURL to the external payment receipt.
receivedstringdate-timeWhen the external payment was recorded.
referencestringReference from the external payment system.
linearray of OrderLineItemrequiredLine items in the order.
Show child attributes
Selected by type.
activatebooleanWhether the subscription waits for the subscriber to activate it rather than being activated on a date.
The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.
Cannot be combined with scheduleActivationAt.
displaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
leasestringToken received when leasing a number. Required when an msisdn is provided from the number pool.
linestringrequiredUnique identifier for this line item within the order.
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
msisdnstringpersonal dataThe phone number for this subscription.
- Leave empty to have one assigned.
- When the number pool is available, you can choose a number from the pool and provide the leaseToken.
- When porting a number, provide the number and porting details.
portingobjectDetails needed to port in a number for this subscription.
Show child attributes
portingbooleanIf true, the number is a port-in.
productstringrequiredThe product offering to create a subscription for.
schedulestringdateDate when the subscription should be activated. Cannot be combined with activateOnDemand.
simobjectThe choice between eSIM and physical SIM plus related device details.
This value is optional while the order is a draft. You must give it before you submit the order.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriberobjectThe person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.
Show child attributes
tempbooleanWhether to use a temporary number until the porting is completed.
If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.
Can only be used when porting in a number (i.e., when msisdn and porting details are provided).
typeenum<string>requiredIdentifies this line item as a new subscription purchase. Always SUBSCRIPTION.
values
SUBSCRIPTION
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent subscription line item in this same order.
Either this or subscriptionId must be provided.
productstringrequiredThe add-on product offering to add.
scheduledstringdateWhen to activate the add-on.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringAn existing subscription to add the add-on to.
Either this or parentLineItemId must be provided.
typeenum<string>requiredIdentifies this line item as adding an add-on to a subscription. Always ADDON.
values
ADDON
linestringrequiredUnique identifier for this line item within the order.
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
parentstringReference to parent line item in this order.
productstringrequiredThe external product offering from the catalog.
quantityinteger>= 1Quantity of the external product.
schedulestringdateDate when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
typeenum<string>requiredIdentifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.
values
EXTERNAL_PRODUCT
descriptionstringDescription of the external item.
fulfillmentstringuriOptional webhook URL for fulfillment notifications.
linestringrequiredUnique identifier for this line item within the order.
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
namestringrequiredName of the external item.
parentstringReference to parent line item in this order.
priceobjectrequiredCustom pricing for the external item.
Show child attributes
quantityinteger>= 1Quantity of the external item.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
taxationstringUS taxation ID for tax calculation.
typeenum<string>requiredIdentifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.
values
EXTERNAL
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.
The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.
values
PLAN_CHANGESIM_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of a subscription.
Show child attributes
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
simobjectThe SIM card change. Give this value only for changeType SIM_CHANGE.
A change of the SIM card of a subscription. The change carries a one-time price.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe identifier of the existing subscription that this line item changes.
typeenum<string>requiredIdentifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.
values
SUBSCRIPTION_CHANGE
addonstringrequiredThe identifier of the existing add-on on the subscription that this line item changes.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the add-on.
values
PLAN_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
planobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of an add-on.
Show child attributes
reasonstringFree-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe subscription containing the add-on to modify.
typeenum<string>requiredIdentifies this line item as a change to an existing add-on. Always ADDON_CHANGE.
values
ADDON_CHANGE
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
*stringorderstringrequiredUnique identifier for the order.
paymentstringThe payment profile session used to set up a payment method for this order, set when the order was submitted with one.
paymentstringThe payment session that collected payment for this order, set when the order was submitted with one.
pricingobjectDetailed pricing information for an order including taxes and discounts.
Show child attributes
amountintegerint64What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.
This is not totalMinor, which answers what the order costs however it is paid. Use this
one to decide whether to ask for a payment method.
calculatedstringdate-timerequiredWhen the pricing was last calculated.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
periodobjectPeriod covered by the initial invoice.
Show child attributes
subtotalintegerint64First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.
taxintegerint64Estimated tax on initial invoice charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total first invoice amount, in minor currency units.
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
billingobjectHow often a recurring price is charged.
Show child attributes
subtotalintegerint64Recurring subtotal after discounts and before taxes, in minor currency units.
taxintegerint64Estimated tax on recurring charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total estimated recurring amount, in minor currency units.
subtotalintegerint64The net of the order after discounts, in minor currency units. When taxIncluded is false,
add the totalDiscountsMinor of each line item to it to get the amount before discounts.
When taxIncluded is true, the discounts came off the total instead, so the amount before
discounts is totalMinor plus the discounts.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
taxbooleanWhether the amounts leave out a tax that is not calculated yet. In a region where the tax
depends on the address, the tax is calculated when the payment starts, and this field is
true until then. When taxIncluded is also true, the tax is a part of totalMinor.
Otherwise the tax is added to it.
taxbooleanWhether every line was priced with its tax as a part of the price. When true, the discounts
came off totalMinor and taxAmountMinor is the tax inside it. When false, the discounts
came off subtotalMinor and the tax was added on top. Absent when the order has no priced
line yet.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
chargedintegerint64What one month this order charges for costs, in minor currency units. Quote this next to
totalMinor on an order that pays for several months at once, because recurringAmountMinor
is what a month costs once the order renews, which is more. Do not divide totalMinor by
chargedMonths instead: on a brand that bills calendar months, the order also charges a
prorated part-month, and that part is in totalMinor but not in these two fields.
chargedintegerHow many consecutive months cost chargedMonthAmountMinor. A part-month first period is not
one of them. The count stops at the first month that costs something else, which is when a
discount ends part way through the months the order pays for.
descriptionstringDescription of what this line item covers.
discountsarray of OrderPricingDiscountThe individual discounts making up totalDiscountsMinor, such as a campaign, a promotion
code, a price list reduction or a binding period discount. The amounts cover everything this
order charges for the line, which is more than one billing period when the order pays for
several at once.
Show child attributes
initialintegerint64Amount for this line item on the first invoice when different from recurring, in minor currency units.
linestringrequiredThe line item in the order that this pricing applies to.
recurringintegerint64Recurring cost for this line item per billing cycle, in minor currency units.
recurringarray of OrderPricingDiscountThe individual discounts inside recurringAmountMinor, for one billing period. Add back the
ones that carry a validTo to get what the line costs after they stop.
Show child attributes
subtotalintegerint64requiredThe net of this line item after discounts, in minor currency units. When taxIncluded is
false, add totalDiscountsMinor to it to get the amount before discounts. When taxIncluded
is true, the discounts came off totalMinor instead.
taxintegerint64Total taxes for this line item, in minor currency units.
taxarray of TaxBreakdownItemThe individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.
Show child attributes
taxbooleanWhether the line was priced with its tax as a part of the price. When true, totalMinor is
the listed price less the discounts and taxAmountMinor is the tax inside it.
totalintegerint64Total discounts for this line item, in minor currency units.
totalintegerint64requiredAmount due for this line item after taxes, fees, and discounts, in minor currency units.
promostringPromotional code applied to this order, if any.
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
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
signingstringThe signing session that captured the customer's signature for this order, set when the order was submitted with one.
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
submittedstringdate-timeWhen the order was submitted for fulfillment.
updatedstringdate-timerequiredWhen the order was last updated.
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
emailstringemailpersonal dataThe email the user logs in with.
namestringThe user's full name.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
userstringThe user's identifier, once the user exists.
validationobjectrequiredThe result of the checks that a submit makes on the order and its line items. The checks make sure that each necessary field is set, and that the customer can buy each product offering. Payment is not part of these checks.
Show child attributes
errorsarray of InlineValidationErrorOrder-level validation errors.
Show child attributes
codeenum<string>deprecatedDeprecated. Use reason.
A code for the problem. An order sets it when the order cannot buy the product offering of a line item:
- NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer.
- ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on.
- OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering.
A problem without a code is a field that is missing or not correct.
values
NOT_AN_INITIAL_OFFERINGADDON_NOT_APPLICABLEOFFERING_CHANGE_NOT_AVAILABLE
messagestringrequiredValidation error message.
propertystringProperty related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").
reasonstringNames the problem. property_required is a missing value, property_invalid is a value with
the wrong format, and property_conflict is two values that cannot occur together. Other
reasons name a business condition, for example not_an_initial_offering. Your client must
accept a reason that it does not know.
isbooleanrequiredWhether the order is valid and ready for submission.
linearray of objectValidation status for each line item.
Show child attributes
errorsarray of InlineValidationErrorValidation errors for this line item.
Show child attributes
isbooleanWhether this line item is valid.
linestringReference to the line item.
missingarray of stringRequired fields that are still missing.
missingarray of stringRequired fields that are still missing.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "billing@example.com",
"name": "John Doe"
},
"completedAt": "2024-01-15T15:00:00Z",
"consents": {
"marketing": "true",
"termsOfService": "true"
},
"createdAt": "2024-01-15T10:00:00Z",
"createdEntities": {
"addons": [
{
"addedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"metadata": {
"propertyName": "string"
},
"productOfferingGroupId": "extra-data-packages",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"updatedAt": "2024-01-20T09:00:00Z",
"createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"licenses": [
{
"activatedAt": "2024-01-15",
"cancelledAt": "2024-06-30",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "PENDING",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "PBX_USER_LEVEL",
"createdByLineItem": "j47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"modifications": [
{
"appliedAt": "2024-01-15T15:00:00Z",
"newProductOfferingId": "po_mobile_premium_plus",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "SUBSCRIPTION_CHANGE",
"createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"subscriptions": [
{
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "PENDING",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "CELL",
"updatedAt": "2024-01-15T10:30:00Z",
"createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
]
},
"customer": {
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
},
"expiresAt": "2024-01-22T10:30:00Z",
"externalPayment": {
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"receivedAt": "2024-01-15T14:30:00Z",
"reference": "ext-payment-ref-123"
},
"lineItems": [
{
"activateOnDemand": true,
"display": "John Doe - Work phone",
"extensions": {
"propertyName": "string"
},
"leaseToken": "lease_8f3b1c2d4e5f6789",
"lineItemId": "line-item-1",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"porting": {
"details": {
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}
},
"portingRequested": true,
"productOfferingId": "mobile-plan-basic",
"scheduleActivationAt": "2024-02-01",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"name": "John Doe"
},
"tempNumber": true,
"type": "SUBSCRIPTION"
}
],
"metadata": {
"propertyName": "string"
},
"orderId": "order-123",
"paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"pricing": {
"amountDueNowMinor": 13739,
"calculatedAt": "2024-01-15T10:30:00Z",
"currency": "USD",
"initialInvoice": {
"period": {
"end": "2024-01-31",
"start": "2024-01-15"
},
"subtotalMinor": 1450,
"taxAmountMinor": 116,
"taxIncluded": true,
"totalMinor": 1566
},
"recurringCosts": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"subtotalMinor": 2999,
"taxAmountMinor": 240,
"taxIncluded": true,
"totalMinor": 3239
},
"subtotalMinor": 12599,
"taxAmountMinor": 1008,
"taxEstimated": false,
"taxIncluded": true,
"totalMinor": 13739,
"lineItems": [
{
"chargedMonthAmountMinor": 14458,
"chargedMonths": 6,
"description": "Premium Plan",
"discounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"initialInvoiceAmountMinor": 1450,
"lineItemId": "line-item-1",
"recurringAmountMinor": 2999,
"recurringDiscounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"subtotalMinor": 2999,
"taxAmountMinor": 247,
"taxBreakdown": [
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}
],
"taxIncluded": true,
"totalDiscountsMinor": 2999,
"totalMinor": 2747
}
]
},
"promoCode": "STUDENT2024",
"requirements": {
"requiresPayment": "NOT_REQUIRED",
"requiresPaymentProfile": "NOT_REQUIRED",
"requiresSigning": "NOT_REQUIRED"
},
"shipping": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
},
"signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
"state": "PENDING",
"submittedAt": "2024-01-15T14:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"user": {
"email": "john.doe@example.com",
"name": "John Doe",
"newUser": true,
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"validation": {
"errors": [
{
"code": "NOT_AN_INITIAL_OFFERING",
"message": "Subscriber name is required.",
"property": "subscriber.name",
"reason": "not_an_initial_offering"
}
],
"isValid": false,
"lineItemValidation": [
{
"errors": [
{
"code": "NOT_AN_INITIAL_OFFERING",
"message": "Subscriber name is required.",
"property": "subscriber.name",
"reason": "not_an_initial_offering"
}
],
"isValid": false,
"lineItemId": "line-item-1",
"missingFields": [
"subscriber.name",
"sim.iccid"
]
}
],
"missingFields": [
"customer",
"billing.address"
]
}
}OrderBilling
Billing information for an order.
For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.
addressobjectThe billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.
The platform reads it for tax only when the customer holds no billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataBilling contact email.
namestringBilling contact name.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "billing@example.com",
"name": "John Doe"
}OrderBillingInput
Billing information for an order.
For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.
addressobjectThe billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.
The platform reads it for tax only when the customer holds no billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataBilling contact email.
namestringBilling contact name.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "billing@example.com",
"name": "John Doe"
}OrderCustomerReference
Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer.
customerstringrequiredThe customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.
authenticatedbooleanrequiredAlways true.
billingobjectBilling configuration and payment preferences for the new customer.
Show child attributes
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
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
contactobjectContact information for the new customer.
Show child attributes
emailstringemailpersonal dataPrimary contact email for the new customer.
msisdnstringphonepersonal dataPrimary contact phone number for the new 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
identitystringpersonal dataA 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.
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
*stringnamestringrequiredName for the new customer.
preferredstringPreferred locale for the customer.
referencestringmax length 255Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.
{
"customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
}OrderCustomerReference_NewCustomer
Details for creating a new customer together with the order.
The customer's default payment profile can be set via the save payment profile endpoint once the customer is created.
If referenceId is provided and a customer already exists with that referenceId, the existing customer will be used instead of creating a new one.
billingobjectBilling configuration and payment preferences for the new customer.
Show child attributes
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
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
contactobjectContact information for the new customer.
Show child attributes
emailstringemailpersonal dataPrimary contact email for the new customer.
msisdnstringphonepersonal dataPrimary contact phone number for the new 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
identitystringpersonal dataA 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.
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
*stringnamestringrequiredName for the new customer.
preferredstringPreferred locale for the customer.
referencestringmax length 255Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"autoPay": true,
"currency": "USD",
"email": "billing@acme.com",
"method": "E_INVOICE"
},
"contact": {
"email": "billing@acme.com",
"msisdn": "+15551234567"
},
"customerType": "CONSUMER",
"identity": "12-3456789",
"metadata": {
"propertyName": "string"
},
"name": "Acme Corporation",
"preferredLocale": "en-US",
"referenceId": "crm-customer-12345"
}OrderCustomerResult
The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.
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.
{
"customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerType": "CONSUMER",
"name": "John Doe",
"newCustomer": true
}OrderCustomerType
The type of customer this order is for. This scopes the order to the customer type's context, which affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it.
For logged in orders, this must match the customer's type.
values
CONSUMERBUSINESS
"CONSUMER"OrderHandoffClaim
The order of a handoff token.
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
orderstringrequiredThe order of the token.
{
"customerType": "CONSUMER",
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}OrderHandoffToken
A token that gives an open order to a checkout. A person with the token can see, change, and pay for the order. Give the token only to the user that the order is for.
expiresstringdate-timerequiredWhen the token expires, 1 hour after its creation. The order has its own expiry.
handoffstringrequiredThe handoff token. We return it only in this response. If you lose it, create a new token.
orderstringrequiredThe order of the token.
{
"expiresAt": "2024-01-15T11:00:00Z",
"handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479",
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}OrderLineItem
A line item in an order representing a billable action or service.
Selected by type.
activatebooleanWhether the subscription waits for the subscriber to activate it rather than being activated on a date.
The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.
Cannot be combined with scheduleActivationAt.
displaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
*stringleasestringToken received when leasing a number. Required when an msisdn is provided from the number pool.
linestringrequiredUnique identifier for this line item within the order.
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
*stringmsisdnstringpersonal dataThe phone number for this subscription.
- Leave empty to have one assigned.
- When the number pool is available, you can choose a number from the pool and provide the leaseToken.
- When porting a number, provide the number and porting details.
portingobjectDetails needed to port in a number for this subscription.
Show child attributes
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
portingbooleanIf true, the number is a port-in.
productstringrequiredThe product offering to create a subscription for.
schedulestringdateDate when the subscription should be activated. Cannot be combined with activateOnDemand.
simobjectThe choice between eSIM and physical SIM plus related device details.
This value is optional while the order is a draft. You must give it before you submit the order.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
esimbooleanrequiredWhether this line item uses eSIM technology.
iccidstringpersonal dataIntegrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.
This feature only applies to certain networks.
imeistringpersonal dataInternational Mobile Equipment Identity for eSIM activation.
Some networks require this to activate the eSIM.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriberobjectThe person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.
Show child attributes
addressobjectThe address where the subscriber uses this subscription. In the US, this is the E911 address.
Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
emailstringemailpersonal dataContact email of the subscriber.
msisdnstringphonepersonal dataContact phone number of the subscriber. May be the same as the subscription's msisdn.
namestringName of the subscriber.
tempbooleanWhether to use a temporary number until the porting is completed.
If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.
Can only be used when porting in a number (i.e., when msisdn and porting details are provided).
typeenum<string>requiredIdentifies this line item as a new subscription purchase. Always SUBSCRIPTION.
values
SUBSCRIPTION
linestringrequiredUnique identifier for this line item within the order.
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
*stringparentstringReference to parent subscription line item in this same order.
Either this or subscriptionId must be provided.
productstringrequiredThe add-on product offering to add.
scheduledstringdateWhen to activate the add-on.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringAn existing subscription to add the add-on to.
Either this or parentLineItemId must be provided.
typeenum<string>requiredIdentifies this line item as adding an add-on to a subscription. Always ADDON.
values
ADDON
linestringrequiredUnique identifier for this line item within the order.
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
*stringparentstringReference to parent line item in this order.
productstringrequiredThe external product offering from the catalog.
quantityinteger>= 1Quantity of the external product.
schedulestringdateDate when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
typeenum<string>requiredIdentifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.
values
EXTERNAL_PRODUCT
descriptionstringDescription of the external item.
fulfillmentstringuriOptional webhook URL for fulfillment notifications.
linestringrequiredUnique identifier for this line item within the order.
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
*stringnamestringrequiredName of the external item.
parentstringReference to parent line item in this order.
priceobjectrequiredCustom pricing for the external item.
Show child attributes
amountintegerint64requiredThe price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD).
currencystringrequiredThe ISO 4217 currency code the price is expressed in. Must match the order currency.
quantityinteger>= 1Quantity of the external item.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
taxationstringUS taxation ID for tax calculation.
typeenum<string>requiredIdentifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.
values
EXTERNAL
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.
The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.
values
PLAN_CHANGESIM_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
*stringplanobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of a subscription.
Show child attributes
productstringrequiredThe plan offering to change to. The platform refuses an offering in the SIM card category.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
simobjectThe SIM card change. Give this value only for changeType SIM_CHANGE.
A change of the SIM card of a subscription. The change carries a one-time price.
Show child attributes
productstringrequiredThe SIM card offering to change to. The offering must be in the SIM card category.
simobjectThe SIM card of the change.
The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect.
The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe identifier of the existing subscription that this line item changes.
typeenum<string>requiredIdentifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.
values
SUBSCRIPTION_CHANGE
addonstringrequiredThe identifier of the existing add-on on the subscription that this line item changes.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the add-on.
values
PLAN_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
*stringplanobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of an add-on.
Show child attributes
productstringrequiredThe add-on offering to change to.
reasonstringFree-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe subscription containing the add-on to modify.
typeenum<string>requiredIdentifies this line item as a change to an existing add-on. Always ADDON_CHANGE.
values
ADDON_CHANGE
{
"activateOnDemand": true,
"display": "John Doe - Work phone",
"extensions": {
"propertyName": "string"
},
"leaseToken": "lease_8f3b1c2d4e5f6789",
"lineItemId": "line-item-1",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"porting": {
"details": {
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}
},
"portingRequested": true,
"productOfferingId": "mobile-plan-basic",
"scheduleActivationAt": "2024-02-01",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"name": "John Doe"
},
"tempNumber": true,
"type": "SUBSCRIPTION"
}OrderLineItemPricing
The calculated price of a single order line item, with its tax, fee, and discount breakdown. Returned by the order price calculation endpoint so you can show a per-item breakdown before the order is submitted. All amounts are in minor units of the order currency (e.g., 2999 = $29.99 when the currency is USD).
chargedintegerint64What one month this order charges for costs, in minor currency units. Quote this next to
totalMinor on an order that pays for several months at once, because recurringAmountMinor
is what a month costs once the order renews, which is more. Do not divide totalMinor by
chargedMonths instead: on a brand that bills calendar months, the order also charges a
prorated part-month, and that part is in totalMinor but not in these two fields.
chargedintegerHow many consecutive months cost chargedMonthAmountMinor. A part-month first period is not
one of them. The count stops at the first month that costs something else, which is when a
discount ends part way through the months the order pays for.
descriptionstringDescription of what this line item covers.
discountsarray of OrderPricingDiscountThe individual discounts making up totalDiscountsMinor, such as a campaign, a promotion
code, a price list reduction or a binding period discount. The amounts cover everything this
order charges for the line, which is more than one billing period when the order pays for
several at once.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
sourceenum<string>What gave the customer the discount:
STANDARDandBINDING_CONTRACTare part of the offering's own terms.PRICE_LISTandPRICE_LIST_DISCOUNTcome from the price list the customer is on.BINDING_PERIODcomes from the contract the customer signed.UPFRONT_PAYMENTis what the customer bought by paying for several periods at once.TAGis a campaign the customer carries.PROMOTION_CODEis the promotional code on the order.
Omitted on an order priced before this field existed.
values
STANDARDBINDING_CONTRACTPRICE_LISTPRICE_LIST_DISCOUNTBINDING_PERIODUPFRONT_PAYMENTTAGPROMOTION_CODE
validstringdateThe first day the discount comes off the price.
validstringdateThe last day the discount comes off the price. Omitted when the discount never stops.
initialintegerint64Amount for this line item on the first invoice when different from recurring, in minor currency units.
linestringrequiredThe line item in the order that this pricing applies to.
recurringintegerint64Recurring cost for this line item per billing cycle, in minor currency units.
recurringarray of OrderPricingDiscountThe individual discounts inside recurringAmountMinor, for one billing period. Add back the
ones that carry a validTo to get what the line costs after they stop.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
sourceenum<string>What gave the customer the discount:
STANDARDandBINDING_CONTRACTare part of the offering's own terms.PRICE_LISTandPRICE_LIST_DISCOUNTcome from the price list the customer is on.BINDING_PERIODcomes from the contract the customer signed.UPFRONT_PAYMENTis what the customer bought by paying for several periods at once.TAGis a campaign the customer carries.PROMOTION_CODEis the promotional code on the order.
Omitted on an order priced before this field existed.
values
STANDARDBINDING_CONTRACTPRICE_LISTPRICE_LIST_DISCOUNTBINDING_PERIODUPFRONT_PAYMENTTAGPROMOTION_CODE
validstringdateThe first day the discount comes off the price.
validstringdateThe last day the discount comes off the price. Omitted when the discount never stops.
subtotalintegerint64requiredThe net of this line item after discounts, in minor currency units. When taxIncluded is
false, add totalDiscountsMinor to it to get the amount before discounts. When taxIncluded
is true, the discounts came off totalMinor instead.
taxintegerint64Total taxes for this line item, in minor currency units.
taxarray of TaxBreakdownItemThe individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.
Show child attributes
amountintegerint64requiredThe amount charged for this tax component, in minor units of the currency of the transaction.
descriptionstringrequiredHuman-readable name of the tax or fee, suitable for display on invoices and receipts.
ratenumberdecimalThe tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.
taxbooleanWhether the line was priced with its tax as a part of the price. When true, totalMinor is
the listed price less the discounts and taxAmountMinor is the tax inside it.
totalintegerint64Total discounts for this line item, in minor currency units.
totalintegerint64requiredAmount due for this line item after taxes, fees, and discounts, in minor currency units.
{
"chargedMonthAmountMinor": 14458,
"chargedMonths": 6,
"description": "Premium Plan",
"discounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"initialInvoiceAmountMinor": 1450,
"lineItemId": "line-item-1",
"recurringAmountMinor": 2999,
"recurringDiscounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"subtotalMinor": 2999,
"taxAmountMinor": 247,
"taxBreakdown": [
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}
],
"taxIncluded": true,
"totalDiscountsMinor": 2999,
"totalMinor": 2747
}OrderLineItemStatus
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
"PENDING"OrderListItem
Optimized order representation for list operations.
createdstringdate-timerequiredWhen the order was created.
customerobjectCustomer 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.
expiresstringdate-timeWhen the order will expire if not submitted.
orderstringrequiredThe unique identifier for the order.
pricingobjectSummary pricing information for the order.
Show child attributes
currencystringrequiredISO 4217 currency code.
totalintegerint64requiredFinal order total including all taxes and fees, in minor currency units.
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
updatedstringdate-timerequiredWhen the order was last updated.
validationenum<string>Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid.
values
VALIDINVALIDPENDING_VALIDATION
{
"createdAt": "2024-01-15T10:00:00Z",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"expiresAt": "2024-01-22T10:30:00Z",
"orderId": "ce0539b4-ec57-4709-b72e-47892586d05a",
"pricing": {
"currency": "USD",
"totalMinor": 13739
},
"state": "PENDING",
"updatedAt": "2024-01-15T10:30:00Z",
"validationStatus": "VALID"
}OrderModification
A modification applied to an existing service during order fulfillment.
appliedstringdate-timeWhen the modification was applied.
newstringThe product offering the entity was changed to.
targetstringrequiredThe subscription or add-on that was modified.
typeenum<string>requiredType of modification applied.
values
SUBSCRIPTION_CHANGEADDON_CHANGE
{
"appliedAt": "2024-01-15T15:00:00Z",
"newProductOfferingId": "po_mobile_premium_plus",
"targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "SUBSCRIPTION_CHANGE"
}OrderPricing
Detailed pricing information for an order including taxes and discounts.
amountintegerint64What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.
This is not totalMinor, which answers what the order costs however it is paid. Use this
one to decide whether to ask for a payment method.
calculatedstringdate-timerequiredWhen the pricing was last calculated.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
periodobjectPeriod covered by the initial invoice.
Show child attributes
endstringdateEnd date of the initial billing period.
startstringdateStart date of the initial billing period.
subtotalintegerint64First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.
taxintegerint64Estimated tax on initial invoice charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total first invoice amount, in minor currency units.
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
billingobjectHow often a recurring price is charged.
Show child attributes
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
subtotalintegerint64Recurring subtotal after discounts and before taxes, in minor currency units.
taxintegerint64Estimated tax on recurring charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total estimated recurring amount, in minor currency units.
subtotalintegerint64The net of the order after discounts, in minor currency units. When taxIncluded is false,
add the totalDiscountsMinor of each line item to it to get the amount before discounts.
When taxIncluded is true, the discounts came off the total instead, so the amount before
discounts is totalMinor plus the discounts.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
taxbooleanWhether the amounts leave out a tax that is not calculated yet. In a region where the tax
depends on the address, the tax is calculated when the payment starts, and this field is
true until then. When taxIncluded is also true, the tax is a part of totalMinor.
Otherwise the tax is added to it.
taxbooleanWhether every line was priced with its tax as a part of the price. When true, the discounts
came off totalMinor and taxAmountMinor is the tax inside it. When false, the discounts
came off subtotalMinor and the tax was added on top. Absent when the order has no priced
line yet.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
linearray of OrderLineItemPricingPricing breakdown per line item.
Show child attributes
chargedintegerint64What one month this order charges for costs, in minor currency units. Quote this next to
totalMinor on an order that pays for several months at once, because recurringAmountMinor
is what a month costs once the order renews, which is more. Do not divide totalMinor by
chargedMonths instead: on a brand that bills calendar months, the order also charges a
prorated part-month, and that part is in totalMinor but not in these two fields.
chargedintegerHow many consecutive months cost chargedMonthAmountMinor. A part-month first period is not
one of them. The count stops at the first month that costs something else, which is when a
discount ends part way through the months the order pays for.
descriptionstringDescription of what this line item covers.
discountsarray of OrderPricingDiscountThe individual discounts making up totalDiscountsMinor, such as a campaign, a promotion
code, a price list reduction or a binding period discount. The amounts cover everything this
order charges for the line, which is more than one billing period when the order pays for
several at once.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
sourceenum<string>What gave the customer the discount:
STANDARDandBINDING_CONTRACTare part of the offering's own terms.PRICE_LISTandPRICE_LIST_DISCOUNTcome from the price list the customer is on.BINDING_PERIODcomes from the contract the customer signed.UPFRONT_PAYMENTis what the customer bought by paying for several periods at once.TAGis a campaign the customer carries.PROMOTION_CODEis the promotional code on the order.
Omitted on an order priced before this field existed.
values
STANDARDBINDING_CONTRACTPRICE_LISTPRICE_LIST_DISCOUNTBINDING_PERIODUPFRONT_PAYMENTTAGPROMOTION_CODE
validstringdateThe first day the discount comes off the price.
validstringdateThe last day the discount comes off the price. Omitted when the discount never stops.
initialintegerint64Amount for this line item on the first invoice when different from recurring, in minor currency units.
linestringrequiredThe line item in the order that this pricing applies to.
recurringintegerint64Recurring cost for this line item per billing cycle, in minor currency units.
recurringarray of OrderPricingDiscountThe individual discounts inside recurringAmountMinor, for one billing period. Add back the
ones that carry a validTo to get what the line costs after they stop.
Show child attributes
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
sourceenum<string>What gave the customer the discount:
STANDARDandBINDING_CONTRACTare part of the offering's own terms.PRICE_LISTandPRICE_LIST_DISCOUNTcome from the price list the customer is on.BINDING_PERIODcomes from the contract the customer signed.UPFRONT_PAYMENTis what the customer bought by paying for several periods at once.TAGis a campaign the customer carries.PROMOTION_CODEis the promotional code on the order.
Omitted on an order priced before this field existed.
values
STANDARDBINDING_CONTRACTPRICE_LISTPRICE_LIST_DISCOUNTBINDING_PERIODUPFRONT_PAYMENTTAGPROMOTION_CODE
validstringdateThe first day the discount comes off the price.
validstringdateThe last day the discount comes off the price. Omitted when the discount never stops.
subtotalintegerint64requiredThe net of this line item after discounts, in minor currency units. When taxIncluded is
false, add totalDiscountsMinor to it to get the amount before discounts. When taxIncluded
is true, the discounts came off totalMinor instead.
taxintegerint64Total taxes for this line item, in minor currency units.
taxarray of TaxBreakdownItemThe individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.
Show child attributes
amountintegerint64requiredThe amount charged for this tax component, in minor units of the currency of the transaction.
descriptionstringrequiredHuman-readable name of the tax or fee, suitable for display on invoices and receipts.
ratenumberdecimalThe tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.
taxbooleanWhether the line was priced with its tax as a part of the price. When true, totalMinor is
the listed price less the discounts and taxAmountMinor is the tax inside it.
totalintegerint64Total discounts for this line item, in minor currency units.
totalintegerint64requiredAmount due for this line item after taxes, fees, and discounts, in minor currency units.
{
"amountDueNowMinor": 13739,
"calculatedAt": "2024-01-15T10:30:00Z",
"currency": "USD",
"initialInvoice": {
"period": {
"end": "2024-01-31",
"start": "2024-01-15"
},
"subtotalMinor": 1450,
"taxAmountMinor": 116,
"taxIncluded": true,
"totalMinor": 1566
},
"recurringCosts": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"subtotalMinor": 2999,
"taxAmountMinor": 240,
"taxIncluded": true,
"totalMinor": 3239
},
"subtotalMinor": 12599,
"taxAmountMinor": 1008,
"taxEstimated": false,
"taxIncluded": true,
"totalMinor": 13739,
"lineItems": [
{
"chargedMonthAmountMinor": 14458,
"chargedMonths": 6,
"description": "Premium Plan",
"discounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"initialInvoiceAmountMinor": 1450,
"lineItemId": "line-item-1",
"recurringAmountMinor": 2999,
"recurringDiscounts": [
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}
],
"subtotalMinor": 2999,
"taxAmountMinor": 247,
"taxBreakdown": [
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}
],
"taxIncluded": true,
"totalDiscountsMinor": 2999,
"totalMinor": 2747
}
]
}OrderPricingDiscount
One reduction applied to a line item, with where it came from and how long it lasts. Use source
to tell a reduction the customer earned from one that every price carries, and validTo to tell
the customer when the price goes back up.
amountintegerint64requiredDiscount amount (positive value), in minor currency units.
namestringrequiredDiscount name or description.
sourceenum<string>What gave the customer the discount:
STANDARDandBINDING_CONTRACTare part of the offering's own terms.PRICE_LISTandPRICE_LIST_DISCOUNTcome from the price list the customer is on.BINDING_PERIODcomes from the contract the customer signed.UPFRONT_PAYMENTis what the customer bought by paying for several periods at once.TAGis a campaign the customer carries.PROMOTION_CODEis the promotional code on the order.
Omitted on an order priced before this field existed.
values
STANDARDBINDING_CONTRACTPRICE_LISTPRICE_LIST_DISCOUNTBINDING_PERIODUPFRONT_PAYMENTTAGPROMOTION_CODE
validstringdateThe first day the discount comes off the price.
validstringdateThe last day the discount comes off the price. Omitted when the discount never stops.
{
"amountMinor": 2999,
"name": "First month free",
"source": "PROMOTION_CODE",
"validFrom": "2024-02-01",
"validTo": "2024-02-01"
}OrderPricingSummary
The price of an order, recalculated whenever the order changes. In regions with complex tax rules (e.g., the US), tax is resolved per jurisdiction from the order's addresses. In other regions, tax depends on customer type but is typically included.
All amounts are in minor units of the currency (e.g., 13739 = $137.39 when the currency is USD).
amountintegerint64What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.
This is not totalMinor, which answers what the order costs however it is paid. Use this
one to decide whether to ask for a payment method.
calculatedstringdate-timerequiredWhen the pricing was last calculated.
currencystringrequiredThe ISO 4217 currency code for all pricing amounts (e.g., "USD").
initialobjectOptional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.
Show child attributes
periodobjectPeriod covered by the initial invoice.
Show child attributes
endstringdateEnd date of the initial billing period.
startstringdateStart date of the initial billing period.
subtotalintegerint64First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.
taxintegerint64Estimated tax on initial invoice charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total first invoice amount, in minor currency units.
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
billingobjectHow often a recurring price is charged.
Show child attributes
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
subtotalintegerint64Recurring subtotal after discounts and before taxes, in minor currency units.
taxintegerint64Estimated tax on recurring charges, in minor currency units.
Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.
taxbooleanWhether every line in this total was priced with its tax as a part of the price.
totalintegerint64Total estimated recurring amount, in minor currency units.
subtotalintegerint64The net of the order after discounts, in minor currency units. When taxIncluded is false,
add the totalDiscountsMinor of each line item to it to get the amount before discounts.
When taxIncluded is true, the discounts came off the total instead, so the amount before
discounts is totalMinor plus the discounts.
taxintegerint64Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.
taxbooleanWhether the amounts leave out a tax that is not calculated yet. In a region where the tax
depends on the address, the tax is calculated when the payment starts, and this field is
true until then. When taxIncluded is also true, the tax is a part of totalMinor.
Otherwise the tax is added to it.
taxbooleanWhether every line was priced with its tax as a part of the price. When true, the discounts
came off totalMinor and taxAmountMinor is the tax inside it. When false, the discounts
came off subtotalMinor and the tax was added on top. Absent when the order has no priced
line yet.
totalintegerint64requiredTotal amount due for the order, in minor currency units.
{
"amountDueNowMinor": 13739,
"calculatedAt": "2024-01-15T10:30:00Z",
"currency": "USD",
"initialInvoice": {
"period": {
"end": "2024-01-31",
"start": "2024-01-15"
},
"subtotalMinor": 1450,
"taxAmountMinor": 116,
"taxIncluded": true,
"totalMinor": 1566
},
"recurringCosts": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"subtotalMinor": 2999,
"taxAmountMinor": 240,
"taxIncluded": true,
"totalMinor": 3239
},
"subtotalMinor": 12599,
"taxAmountMinor": 1008,
"taxEstimated": false,
"taxIncluded": true,
"totalMinor": 13739
}OrderRequirement
Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.
- NOT_REQUIRED: The step does not apply; the order can be submitted without it.
- OPTIONAL: The step may be completed, but the order can be submitted without it.
- REQUIRED: The step must be completed and its session reference provided when submitting the order.
values
NOT_REQUIREDOPTIONALREQUIRED
"NOT_REQUIRED"OrderState
The status of an order in its lifecycle.
- PENDING: Order is in cart state, can be modified
- PENDING_PAYMENT: Order is locked and awaiting payment completion
- SUBMITTED: Order has been submitted for processing
- PENDING_APPROVAL: Order is pending approval
- PROCESSING: Order is being fulfilled
- COMPLETED: Order has been successfully fulfilled
- CANCELLED: Order was cancelled before completion
- EXPIRED: Order expired due to inactivity
- FAILED: Order fulfillment failed
values
PENDINGPENDING_PAYMENTSUBMITTEDPENDING_APPROVALPROCESSINGCOMPLETEDCANCELLEDEXPIREDFAILED
"PENDING"OrderUserReference
The person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order.
userstringrequiredThe user's internal ID.
authenticatedbooleanrequiredAlways true.
emailstringemailpersonal datarequiredThe email the user logs in with and receives order confirmations on.
identitystringpersonal dataA 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.
addressobjectdeprecatedDeprecated. The platform does not store this address. A user is a sign-in
identity, and the address of the person belongs to the customer that pays.
Give the address in customer instead.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
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
*stringmsisdnstringphonepersonal dataThe user's phone number.
namestringrequiredThe user's full name.
{
"userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
}OrderUserReference_NewUser
Details for creating a new user together with the order. The user is created when payment is initiated, or at submission for orders that collect no payment, and can then log in to manage the services they ordered.
emailstringemailpersonal datarequiredThe email the user logs in with and receives order confirmations on.
identitystringpersonal dataA 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.
addressobjectdeprecatedDeprecated. The platform does not store this address. A user is a sign-in
identity, and the address of the person belongs to the customer that pays.
Give the address in customer instead.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
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
*stringmsisdnstringphonepersonal dataThe user's phone number.
namestringrequiredThe user's full name.
{
"email": "john.doe@example.com",
"identity": "12-3456789",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"name": "John Doe"
}OrderUserResult
The person who will log in and manage the services in this order.
For a new user, userId is absent until the user is actually created, which happens when payment is initiated or, for orders that collect no payment, at submission.
emailstringemailpersonal dataThe email the user logs in with.
namestringThe user's full name.
newbooleanrequiredWhether this user is created as part of fulfilling the order.
userstringThe user's identifier, once the user exists.
{
"email": "john.doe@example.com",
"name": "John Doe",
"newUser": true,
"userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479"
}Pagination
Cursor-based pagination information returned by list endpoints.
Pass nextCursor as the cursor query parameter of the next request to fetch the following page.
nextstring | nullrequiredOpaque token for fetching the next page. Null when no more results.
{
"nextCursor": "eyJvZmZzZXQiOjEwMH0"
}PauseSubscriptionRequest
Request to pause a subscription. The customer stops paying and service is disabled.
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
*stringscheduledstringdateEarliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.
{
"metadata": {
"propertyName": "string"
},
"scheduledAt": "2024-02-01"
}PaymentAttempt
A single charge attempt against a payment intent.
amountintegerint64requiredThe amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
chargedstringdate-timeWhen the charge was made.
createdstringdate-timerequiredWhen the attempt was created.
currencystringrequiredThe ISO 4217 currency code the attempt was charged in (e.g., "USD").
paymentstringrequiredThe unique identifier for this charge attempt.
reasonstringFailure reason when the attempt did not succeed.
resultenum<string>requiredWhether the charge attempt succeeded or failed.
values
SUCCEEDEDFAILED
{
"amountMinor": 2900,
"chargedAt": "2024-01-15T10:00:00Z",
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
"reason": "card_declined",
"result": "SUCCEEDED"
}PaymentIntent
The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items.
A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice.
amountintegerint64requiredThe total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
attemptsarray of PaymentAttemptrequiredCharge attempts made against this payment intent, most recent first.
Show child attributes
amountintegerint64requiredThe amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
chargedstringdate-timeWhen the charge was made.
createdstringdate-timerequiredWhen the attempt was created.
currencystringrequiredThe ISO 4217 currency code the attempt was charged in (e.g., "USD").
paymentstringrequiredThe unique identifier for this charge attempt.
reasonstringFailure reason when the attempt did not succeed.
resultenum<string>requiredWhether the charge attempt succeeded or failed.
values
SUCCEEDEDFAILED
createdstringdate-timerequiredWhen the payment intent was created.
currencystringrequiredThe ISO 4217 currency code the amount is collected in (e.g., "USD").
customerstringrequiredThe customer this payment intent collects from.
descriptionstringA human-readable description of what is being collected.
discountsarray of PaymentIntentDiscountrequiredReductions applied to the payment intent as a whole rather than to one billed line.
Show child attributes
amountintegerint64requiredThe positive amount deducted, in minor units of the payment intent currency.
descriptionstringrequiredWhy the payment intent was reduced.
duestringdate-timeWhen the amount is due.
linearray of PaymentIntentLineItemrequiredThe items that make up the collected amount.
Show child attributes
amountintegerint64requiredThe base cost of the line item before discounts, in minor units of the payment intent's
currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless
includesTax is true and they are a part of it.
descriptionstringrequiredWhat this line item represents.
discountsarray of objectDiscounts applied to this line item.
Show child attributes
amountintegerint64requiredThe discounted amount (positive value), in minor units of the payment intent's currency.
descriptionstringrequiredWhat the discount is for.
includesbooleanWhether the taxes are a part of amountMinor rather than added to it.
licensestringThe license this line item is associated with, if any.
subscriptionstringThe subscription this line item is associated with, if any.
taxesarray of objectTaxes applied to this line item.
Show child attributes
amountintegerint64requiredThe tax amount, in minor units of the payment intent's currency.
descriptionstringrequiredThe tax component applied (e.g., a named tax and its rate).
paymentstringrequiredThe unique identifier for this payment intent.
refundsarray of PaymentRefundrequiredRefunds issued against this payment intent.
Show child attributes
amountintegerint64requiredThe refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
createdstringdate-timerequiredWhen the refund was created.
currencystringrequiredThe ISO 4217 currency code the refund is issued in (e.g., "USD").
reasonenum<string>Why the refund was issued.
values
UNKNOWNDUPLICATEFRAUDULENTREQUESTED_BY_CUSTOMERDISPUTE_LOST
refundstringrequiredThe unique identifier for this refund.
statusenum<string>requiredCurrent stage of the refund.
values
PENDINGSUCCEEDEDFAILEDCANCELEDREQUIRES_ACTION
statusenum<string>requiredCurrent stage of a payment intent as it is collected through the payment provider.
- UNKNOWN: The platform has no supported mapping for the current provider state.
- PENDING: Created, no charge attempted yet.
- REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
- PROCESSING: A charge is in flight with the payment provider.
- SUCCEEDED: The full amount has been collected.
- REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
- CANCELED: Collection was canceled and no further charges will be attempted.
values
UNKNOWNPENDINGREQUIRES_ACTIONPROCESSINGSUCCEEDEDREQUIRES_PAYMENT_METHODCANCELED
updatedstringdate-timerequiredWhen the payment intent was last updated.
{
"amountMinor": 2900,
"attempts": [
{
"amountMinor": 2900,
"chargedAt": "2024-01-15T10:00:00Z",
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
"reason": "card_declined",
"result": "SUCCEEDED"
}
],
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"description": "Mobile subscription renewal",
"discounts": [
{
"amountMinor": 1000,
"description": "Goodwill credit"
}
],
"dueAt": "2024-01-15T10:00:00Z",
"lineItems": [
{
"amountMinor": 2900,
"description": "Mobile subscription - Premium Plan",
"discounts": [
{
"amountMinor": 500,
"description": "Loyalty discount"
}
],
"includesTax": false,
"licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
"subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
"taxes": [
{
"amountMinor": 725,
"description": "VAT 25%"
}
]
}
],
"paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
"refunds": [
{
"amountMinor": 2900,
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"reason": "REQUESTED_BY_CUSTOMER",
"refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
"status": "SUCCEEDED"
}
],
"status": "SUCCEEDED",
"updatedAt": "2024-01-15T10:00:00Z"
}PaymentIntentDiscount
A reduction applied to the payment intent as a whole rather than to one billed line.
amountintegerint64requiredThe positive amount deducted, in minor units of the payment intent currency.
descriptionstringrequiredWhy the payment intent was reduced.
{
"amountMinor": 1000,
"description": "Goodwill credit"
}PaymentIntentLineItem
A single billed item contributing to a payment intent's amount.
amountintegerint64requiredThe base cost of the line item before discounts, in minor units of the payment intent's
currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless
includesTax is true and they are a part of it.
descriptionstringrequiredWhat this line item represents.
discountsarray of objectDiscounts applied to this line item.
Show child attributes
amountintegerint64requiredThe discounted amount (positive value), in minor units of the payment intent's currency.
descriptionstringrequiredWhat the discount is for.
includesbooleanWhether the taxes are a part of amountMinor rather than added to it.
licensestringThe license this line item is associated with, if any.
subscriptionstringThe subscription this line item is associated with, if any.
taxesarray of objectTaxes applied to this line item.
Show child attributes
amountintegerint64requiredThe tax amount, in minor units of the payment intent's currency.
descriptionstringrequiredThe tax component applied (e.g., a named tax and its rate).
{
"amountMinor": 2900,
"description": "Mobile subscription - Premium Plan",
"discounts": [
{
"amountMinor": 500,
"description": "Loyalty discount"
}
],
"includesTax": false,
"licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
"subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
"taxes": [
{
"amountMinor": 725,
"description": "VAT 25%"
}
]
}PaymentIntentListItem
A payment intent without its nested attempts, refunds, and line items, optimized for list views.
amountintegerint64requiredThe total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
createdstringdate-timerequiredWhen the payment intent was created.
currencystringrequiredThe ISO 4217 currency code the amount is collected in (e.g., "USD").
customerstringrequiredThe customer this payment intent collects from.
descriptionstringA human-readable description of what is being collected.
duestringdate-timeWhen the amount is due.
paymentstringrequiredThe unique identifier for this payment intent.
statusenum<string>requiredCurrent stage of a payment intent as it is collected through the payment provider.
- UNKNOWN: The platform has no supported mapping for the current provider state.
- PENDING: Created, no charge attempted yet.
- REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
- PROCESSING: A charge is in flight with the payment provider.
- SUCCEEDED: The full amount has been collected.
- REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
- CANCELED: Collection was canceled and no further charges will be attempted.
values
UNKNOWNPENDINGREQUIRES_ACTIONPROCESSINGSUCCEEDEDREQUIRES_PAYMENT_METHODCANCELED
typeenum<string>requiredWhat the payment intent collects.
- UNKNOWN: The platform does not have a supported type for this intent.
- PREPAID_RENEWAL: A scheduled prepaid subscription renewal.
- TOPUP: An immediate prepaid balance or allowance top-up.
- INITIAL_ORDER: Payment collected while placing an order.
values
UNKNOWNPREPAID_RENEWALTOPUPINITIAL_ORDER
updatedstringdate-timerequiredWhen the payment intent was last updated.
{
"amountMinor": 2900,
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"description": "Mobile subscription renewal",
"dueAt": "2024-01-15T10:00:00Z",
"paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
"status": "SUCCEEDED",
"type": "PREPAID_RENEWAL",
"updatedAt": "2024-01-15T10:00:00Z"
}PaymentIntentStatus
Current stage of a payment intent as it is collected through the payment provider.
- UNKNOWN: The platform has no supported mapping for the current provider state.
- PENDING: Created, no charge attempted yet.
- REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
- PROCESSING: A charge is in flight with the payment provider.
- SUCCEEDED: The full amount has been collected.
- REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
- CANCELED: Collection was canceled and no further charges will be attempted.
ExampleSUCCEEDED
values
UNKNOWNPENDINGREQUIRES_ACTIONPROCESSINGSUCCEEDEDREQUIRES_PAYMENT_METHODCANCELED
"SUCCEEDED"PaymentIntentType
What the payment intent collects.
- UNKNOWN: The platform does not have a supported type for this intent.
- PREPAID_RENEWAL: A scheduled prepaid subscription renewal.
- TOPUP: An immediate prepaid balance or allowance top-up.
- INITIAL_ORDER: Payment collected while placing an order.
ExamplePREPAID_RENEWAL
values
UNKNOWNPREPAID_RENEWALTOPUPINITIAL_ORDER
"PREPAID_RENEWAL"PaymentProvider
Payment service provider that processes the transaction.
ExampleSTRIPE
values
STRIPEBILLOGRAM
"STRIPE"PaymentRefund
A refund issued against a payment intent.
amountintegerint64requiredThe refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).
createdstringdate-timerequiredWhen the refund was created.
currencystringrequiredThe ISO 4217 currency code the refund is issued in (e.g., "USD").
reasonenum<string>Why the refund was issued.
values
UNKNOWNDUPLICATEFRAUDULENTREQUESTED_BY_CUSTOMERDISPUTE_LOST
refundstringrequiredThe unique identifier for this refund.
statusenum<string>requiredCurrent stage of the refund.
values
PENDINGSUCCEEDEDFAILEDCANCELEDREQUIRES_ACTION
{
"amountMinor": 2900,
"createdAt": "2024-01-15T10:00:00Z",
"currency": "USD",
"reason": "REQUESTED_BY_CUSTOMER",
"refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
"status": "SUCCEEDED"
}PaymentSession
A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow, let the customer pay, then pass its paymentSessionId when you submit the order.
There are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the customer to that page. An embedded session (create it with hosted set to false) gives you providerContext, and you show the payment form inside your own checkout page.
Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds.
cancelstringThe URL the customer is redirected to if they cancel the payment.
createdstringdate-timerequiredWhen this payment session was created.
hostedstringuriThe hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.
metadataobject with string keysrequiredCustom key-value pairs for additional payment session information.
Show child attributes
*stringorderstringrequiredThe unique identifier of the order this payment session is for.
paymentstringThe saved payment method to use for this payment (for returning customers).
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
paymentstringrequiredThe unique identifier for this payment session.
providerobjectWhat the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead.
This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider.
Show child attributes
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
stripeobjectThe Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
Show child attributes
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
returnstringThe URL the customer is redirected to after payment completion.
savebooleanrequiredWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
statusenum<string>requiredCurrent status of a payment session lifecycle.
values
PENDINGREQUIRES_ACTIONCOMPLETEDFAILEDCANCELEDEXPIRED
updatedstringdate-timerequiredWhen this payment session was last updated.
{
"cancelUrl": "https://example.com/order/checkout",
"createdAt": "2024-09-29T10:00:00Z",
"hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
"metadata": {
"campaign": "summer_2024",
"source": "mobile_app"
},
"orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
"paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
"paymentProvider": "STRIPE",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"providerContext": {
"paymentProvider": "STRIPE",
"stripe": {
"clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
"connectedAccountId": "acct_1H8x2vLkdIwHu7ix",
"publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9"
}
},
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true,
"status": "PENDING",
"updatedAt": "2024-09-29T10:30:00Z"
}PaymentSessionBranding
The colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form.
backgroundstringpattern ^#[0-9a-fA-F]{6}$The background color of the payment form, as a hex value with a leading number sign.
borderenum<string>The shape of the buttons and the input fields of the payment form.
values
PILLRECTANGULARROUNDED
buttonstringpattern ^#[0-9a-fA-F]{6}$The color of the payment button, as a hex value with a leading number sign.
displaystringmax length 100The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms.
{
"backgroundColor": "#ffffff",
"borderStyle": "PILL",
"buttonColor": "#0cf68c",
"displayName": "Seamless"
}PaymentSessionProviderContext
What the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead.
This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider.
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
stripeobjectThe Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
Show child attributes
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
{
"paymentProvider": "STRIPE",
"stripe": {
"clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
"connectedAccountId": "acct_1H8x2vLkdIwHu7ix",
"publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9"
}
}PaymentSessionStatus
Current status of a payment session lifecycle.
ExamplePENDING
values
PENDINGREQUIRES_ACTIONCOMPLETEDFAILEDCANCELEDEXPIRED
"PENDING"PortingDetails
Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
accountstringThe account number with the current provider.
If not provided here, must be provided in the future for activation on-demand.
addressobjectrequiredThe address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
firststringpersonal datarequiredThe first name of the account holder at the current provider.
laststringpersonal datarequiredThe last name of the account holder at the current provider.
passcodestringThe passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.
If not provided here, must be provided in the future for activation on-demand.
identitystringpersonal datarequiredThe identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.
{
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}PortingDetailsSweden
Information required to port a Swedish phone number. Swedish carriers approve a transfer based on the national identity number of the number's current owner, so no account number or PIN is needed.
identitystringpersonal datarequiredThe identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.
{
"identity": "199001011234"
}PortingDetailsUS
Information required to port a US phone number. Provide firstName, lastName, and address in the initial request; accountNumber and passcode (often called a Number Transfer PIN) may be omitted at first but must be supplied before the port can be activated. US carriers validate a transfer against the losing carrier's account records, and mismatches are the most common cause of rejected ports, so these values must match the losing carrier's records exactly.
accountstringThe account number with the current provider.
If not provided here, must be provided in the future for activation on-demand.
addressobjectrequiredThe address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
firststringpersonal datarequiredThe first name of the account holder at the current provider.
laststringpersonal datarequiredThe last name of the account holder at the current provider.
passcodestringThe passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.
If not provided here, must be provided in the future for activation on-demand.
{
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}PortingDirection
The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
"INBOUND"PortingEligibilityResult
Result of number porting eligibility check.
eligiblebooleanrequiredWhether the number is eligible for porting.
ineligibilitystringReason why number is not eligible (only present if eligible is false).
msisdnstringphonepersonal datarequiredThe phone number that was checked.
networkstringThe identifier for the current network provider, if detectable
{
"eligible": true,
"ineligibilityReason": "Number not found or not portable",
"msisdn": "+15551234567",
"networkProviderId": "tmobile-us"
}PortingStatus
Current status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
"PENDING"Price
The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
billingobjectHow often a recurring price is charged.
Show child attributes
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
durationobjectrequiredA length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
*integerint64customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingintegerrequiredHow many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
{
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
}PriceDiscount
A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
{
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}PriceType
How the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
"ONE_TIME"ProductCatalogSection
A heading in a product catalog, and the product offerings under it in the order that a checkout shows them.
descriptionstringThe text under the heading. Absent when the section has none.
namestringrequiredThe heading of the section.
productstringrequiredUnique identifier for the section.
productarray of stringrequiredThe product offerings in the section, in display order.
{
"description": "Plans with unlimited calls and texts",
"name": "Mobile plans",
"productCatalogSectionId": "0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90",
"productOfferingIds": [
"string"
]
}ProductCategory
A product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
ExamplePRODUCT_CATEGORY_SUBSCRIPTION_CELL
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
"PRODUCT_CATEGORY_SUBSCRIPTION_CELL"ProductOffering
A product offering is a product combined with a price that is offered to customers.
The offering's type and category are available via the nested product object.
See ProductType and ProductCategory schemas for available values and their meanings.
addonarray of ProductCategoryList of product categories this addon is applicable for.
Only populated when type is SUBSCRIPTION_ADDON.
For example, a TRAVEL_ESIM_PACKAGE addon might be applicable to TRAVEL_ESIM subscriptions.
broadbandobjectThe values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price.
Show child attributes
additionalnumberrequiredThe amount of data, in GB, that overUsageDataPriceMinor buys. Always 0, because the platform sells no data after the allowance.
earlyintegerint64requiredThe fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee.
monthlyarray of BroadbandFactsFeerequiredThe fees that the provider adds to the monthly price.
Show child attributes
amountintegerint64requiredThe amount of the fee, in minor currency units.
namestringrequiredWhat the label calls the fee.
overintegerint64requiredThe price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price.
planstringrequired15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan
identifier on the label is M, then the FCC Registration Number of the brand, then this code.
singlearray of BroadbandFactsFeerequiredThe fees that the customer pays one time, when they buy the plan.
Show child attributes
amountintegerint64requiredThe amount of the fee, in minor currency units.
namestringrequiredWhat the label calls the fee.
unlimitedbooleanrequiredTrue when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product.
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
descriptionstringDescription of the product offering.
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
internalstringInternal description of the product offering for operational use only.
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
*stringnamestringrequiredName of the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
intervalintegerrequiredThe quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.
periodenum<string>requiredThe unit of time between charges. Currently only monthly billing is supported.
values
MONTHLY
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
durationobjectrequiredA length of time, expressed as a count of some unit.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
*integerint64customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingintegerrequiredHow many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
productobjectrequiredEmbedded representation of a product.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
featuresobjectThe features included with the product, if any. Typically used for telecom products.
Show child attributes
activationenum<string>How the travel eSIM package activates.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
values
INSTANTFIRST_USE
countriesarray of stringISO 3166-1 alpha-3 country codes where the product provides coverage.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
Use the countries query parameter on list endpoints to filter by coverage.
datanumberMegabytes of data included with the product. Present for cellular, data, and travel eSIM products.
includedintegerOutbound call seconds included with the product. Present for cellular subscription categories.
includedintegerNumber of SMS messages included with the product. Present for cellular subscription categories.
regionsarray of stringNamed regions covered by the product.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
Use the regions query parameter on list endpoints to filter by coverage.
simenum<string>The SIM format for a SIM card product.
values
PSIMESIM
validityintegerNumber of days the product is valid for.
Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).
internalstringrequiredThe name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.
networkstringThe unique identifier for the network provider.
productstringrequiredThe unique identifier for the product.
typeenum<string>requiredThe type of product offering determines how it can be used and what kind of resource it creates.
SUBSCRIPTION Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).
- Includes categories like
SUBSCRIPTION_CELL,TRAVEL_ESIM - Can be created via order or directly depending on configuration
- Has its own lifecycle (activation, suspension, termination)
SUBSCRIPTION_ADDON Adds features or resources to an existing subscription.
- Includes categories like
TRAVEL_ESIM_PACKAGE - Must be attached to a parent subscription
LICENSE Creates a license for business/PBX features.
- Typically used for enterprise telephony features
EXTERNAL_PRODUCT Represents purchasable items outside the core telecom platform.
- Can only be ordered via orders, not created directly
SIM_CARD Replaces the SIM card for an existing subscription through a subscription change order.
values
SUBSCRIPTIONSUBSCRIPTION_ADDONLICENSEEXTERNAL_PRODUCTSIM_CARD
productstringrequiredUnique identifier for the product offering.
richstringRich HTML content with detailed information about the product offering.
statusenum<string>deprecatedrequiredDeprecated. Use versionStatus instead.
The status of the product offering.
Archived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions.
values
AVAILABLEARCHIVED
usparray of stringShort plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.
versionenum<string>requiredThe stage of this version of the product offering.
DRAFT: The brand edits the version. Nobody can order it.TESTING: The brand tests the version. Nobody can order it.PUBLISHED: Each customer can order the version.UNPUBLISHED: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it.ARCHIVED: Nobody can order the version. Existing subscriptions keep it.
values
DRAFTTESTINGPUBLISHEDUNPUBLISHEDARCHIVED
{
"addonCategories": [
"PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
],
"broadbandFacts": {
"additionalDataIncrementGb": 0,
"earlyTerminationFeeMinor": 0,
"monthlyProviderFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"overUsageDataPriceMinor": 0,
"planCode": "FLEXSTANDARD001",
"singlePurchaseFees": [
{
"amountMinor": 21,
"name": "Federal Universal Service Fund"
}
],
"unlimitedData": false
},
"customerType": "CONSUMER",
"description": "Basic mobile plan with 5GB data and unlimited calls",
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"internalDescription": "seamless_cell_10gb_us",
"metadata": {
"propertyName": "string"
},
"name": "Seamless 10GB",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"product": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"features": {
"activationType": "INSTANT",
"countries": [
"USA",
"CAN",
"MEX"
],
"dataMb": 2048,
"includedCallSeconds": 1000,
"includedSms": 500,
"regions": [
"NORTH_AMERICA"
],
"simCardType": "PSIM",
"validityDays": 30
},
"internalName": "us-mobile-unlimited-5gb",
"networkProviderId": "tmobile-us",
"productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
"type": "SUBSCRIPTION"
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"richContent": "<h3>Features</h3><ul><li>5GB monthly data</li><li>Unlimited calls & texts</li><li>No setup fees</li></ul>",
"status": "AVAILABLE",
"uspList": [
"5GB of data every month",
"Unlimited calls and texts",
"No setup fee"
],
"versionStatus": "PUBLISHED"
}ProductOfferingChangeSchedule
The schedule type for when a product offering change can take effect.
- INSTANT: The change takes effect at once
- FIRST_OF_NEXT_MONTH: The change takes effect on the first day of the next calendar month
- NEXT_RENEWAL_DAY: The change takes effect on the next renewal date
- NEXT_PAYMENT_DAY: The change takes effect on the next payment day, when the days already paid for run out
- END_OF_PAID_PERIOD: The change takes effect the day after the current paid period ends
- END_OF_BINDING_PERIOD: The change takes effect the day after the binding period ends
values
INSTANTFIRST_OF_NEXT_MONTHNEXT_RENEWAL_DAYNEXT_PAYMENT_DAYEND_OF_PAID_PERIODEND_OF_BINDING_PERIOD
"INSTANT"ProductOfferingGroup
A product group organizes related product offerings.
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
{
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
}ProductOfferingOption
A product offering option available for subscription changes with scheduling information.
changeenum<string>requiredThe schedule type for when a product offering change can take effect.
- INSTANT: The change takes effect at once
- FIRST_OF_NEXT_MONTH: The change takes effect on the first day of the next calendar month
- NEXT_RENEWAL_DAY: The change takes effect on the next renewal date
- NEXT_PAYMENT_DAY: The change takes effect on the next payment day, when the days already paid for run out
- END_OF_PAID_PERIOD: The change takes effect the day after the current paid period ends
- END_OF_BINDING_PERIOD: The change takes effect the day after the binding period ends
values
INSTANTFIRST_OF_NEXT_MONTHNEXT_RENEWAL_DAYNEXT_PAYMENT_DAYEND_OF_PAID_PERIODEND_OF_BINDING_PERIOD
changestringdaterequiredThe date when the product offering change can take effect.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
{
"changeSchedule": "INSTANT",
"changeScheduleDate": "2024-02-01",
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}ProductOfferingVersionStatus
The stage of this version of the product offering.
DRAFT: The brand edits the version. Nobody can order it.TESTING: The brand tests the version. Nobody can order it.PUBLISHED: Each customer can order the version.UNPUBLISHED: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it.ARCHIVED: Nobody can order the version. Existing subscriptions keep it.
ExamplePUBLISHED
values
DRAFTTESTINGPUBLISHEDUNPUBLISHEDARCHIVED
"PUBLISHED"ProductType
The type of product offering determines how it can be used and what kind of resource it creates.
SUBSCRIPTION Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).
- Includes categories like
SUBSCRIPTION_CELL,TRAVEL_ESIM - Can be created via order or directly depending on configuration
- Has its own lifecycle (activation, suspension, termination)
SUBSCRIPTION_ADDON Adds features or resources to an existing subscription.
- Includes categories like
TRAVEL_ESIM_PACKAGE - Must be attached to a parent subscription
LICENSE Creates a license for business/PBX features.
- Typically used for enterprise telephony features
EXTERNAL_PRODUCT Represents purchasable items outside the core telecom platform.
- Can only be ordered via orders, not created directly
SIM_CARD Replaces the SIM card for an existing subscription through a subscription change order.
ExampleSUBSCRIPTION
values
SUBSCRIPTIONSUBSCRIPTION_ADDONLICENSEEXTERNAL_PRODUCTSIM_CARD
"SUBSCRIPTION"ResetNetworkServicesRequest
Confirms that the user approved a temporary interruption while network services are reset.
confirmedbooleanrequiredMust be true after the user explicitly approves the temporary service interruption.
{
"confirmed": true
}ResetNetworkServicesResult
Current state of a subscription network-services reset.
createdstringdate-timeWhen the reset workflow action was created.
finishedstringdate-timeWhen execution finished, if it has finished.
networkstringrequiredNetwork provider selected for this subscription.
observedstringdate-timerequiredWhen this status was read.
outcomeenum<string>requiredWhether a reset was started or an existing recent reset was returned.
values
STARTEDALREADY_RUNNINGRECENT_SUCCESSRECENT_FAILUREOPERATOR_UNSUPPORTED
startedstringdate-timeWhen execution started, if it has started.
statusenum<string>requiredCurrent workflow state.
values
PENDINGRUNNINGSUCCEEDEDFAILEDUNSUPPORTED
subscriptionstringIdentifier of the reset workflow action. Absent when the network provider is unsupported.
subscriptionstringrequiredSubscription whose network services are being reset.
{
"createdAt": "2024-01-15T10:30:00Z",
"finishedAt": "2024-01-15T10:30:00Z",
"networkProvider": "string",
"observedAt": "2024-01-15T10:30:00Z",
"outcome": "STARTED",
"startedAt": "2024-01-15T10:30:00Z",
"status": "PENDING",
"subscriptionActionId": "string",
"subscriptionId": "string"
}RestoreSubscriptionRequest
Request to restore a suspended, paused, or blocked subscription back to active state.
allowedarray of SubscriptionStatusCurrent statuses from which this request can restore the subscription. If omitted, the request can restore all supported statuses.
bararray of BarReasonmin items 1The reasons of the bars to remove from a BLOCKED subscription. The barReasons field of the subscription lists them.
The subscription is activated only when no other bar stays. Otherwise it stays BLOCKED with the bars that stay.
If omitted, the request removes every bar. If the subscription has no bar with one of these reasons, the request fails with 412.
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
*stringscheduledstringdateRestore the subscription on a specific date.
{
"allowedCurrentStatuses": [
"PENDING"
],
"barReasons": [
"MISSING_PAYMENT"
],
"metadata": {
"propertyName": "string"
},
"scheduledAt": "2024-02-01"
}RoamingCostControl
The roaming cost-control setting for one subscription. This cost limit is separate from roaming data allowances and top-up balances.
currencystringThe currency of limitMinor. It is present only when state is ACTIVE.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
limitintegerint64>= 0The configured cost limit in minor currency units. It is present only when state is ACTIVE.
observedstringdate-timerequiredThe time when the platform read this setting.
providerstringrequiredThe network provider that supplies the setting.
stateenum<string>requiredThe availability and configuration state of roaming cost control.
values
ACTIVENOT_CONFIGUREDUNSUPPORTEDUNAVAILABLE
subscriptionstringrequiredThe subscription that owns this roaming cost-control setting.
{
"currency": "USD",
"limitMinor": 52000,
"observedAt": "2024-01-15T10:30:00Z",
"provider": "telia",
"state": "ACTIVE",
"subscriptionId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
}SearchDevicesRequest
Request to find devices by name.
Use this when the customer knows their device by its everyday name and not by its IMEI, for example to find out whether it supports eSIM before they order.
limitinteger>= 1<= 50default 20The largest number of devices to return.
querystringmin length 2requiredPart of the device name to match, such as the brand, the model, or both.
{
"limit": 20,
"query": "iPhone 15"
}Shipping
Shipping information for order fulfillment. Only required if the order contains shippable items.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
}ShippingInput
Shipping information for order fulfillment. Only required if the order contains shippable items.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
}SimType
The technology type of the SIM card.
- PHYSICAL: A plastic SIM card that is shipped and inserted into the device
- ESIM: An embedded SIM profile that is downloaded digitally to the device, typically via QR code
values
PHYSICALESIM
"PHYSICAL"StartEmailLoginRequest
Request to initiate an email-based login flow. A verification code will be sent to the provided email address.
emailstringemailpersonal datarequiredThe email address to send the verification code to.
{
"email": "john.doe@example.com"
}StartEmailLoginResponse
Response from initiating an email login. Contains the nonce needed for verification and timing information.
createdstringdate-timerequiredWhen the authentication request was created.
expiresstringdate-timerequiredWhen the verification code will expire.
expiresintegerrequiredNumber of seconds until the verification code expires.
noncestringrequiredToken to reference this authentication request during verification.
{
"createdAt": "2024-01-15T10:30:00Z",
"expiresAt": "2024-01-15T10:35:00Z",
"expiresIn": 300,
"nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Storefront
The product catalogs that a storefront sells from, and the sections that it shows their product offerings in.
customerenum<string>requiredThe kind of customer that these catalogs sell to.
Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
initialarray of stringThe initial product offerings of these catalogs. A customer can order them as a new subscription or as an external product. A storefront with no sections shows these product offerings.
productarray of stringrequiredThe product catalogs that the storefront sells from. Empty when no catalog applies.
sectionsarray of ProductCatalogSectionrequiredThe sections of these catalogs, in display order. A section gives only initial product offerings.
Show child attributes
descriptionstringThe text under the heading. Absent when the section has none.
namestringrequiredThe heading of the section.
productstringrequiredUnique identifier for the section.
productarray of stringrequiredThe product offerings in the section, in display order.
simarray of SimTypeThe SIM types that the storefront sells with a new subscription. A subscription line with another SIM type cannot go through the checkout of the storefront. Empty when the storefront sells no SIM type.
{
"customerType": "CONSUMER",
"initialProductOfferingIds": [
"string"
],
"productCatalogIds": [
"string"
],
"sections": [
{
"description": "Plans with unlimited calls and texts",
"name": "Mobile plans",
"productCatalogSectionId": "0b6f3c1e-8d2a-4f7b-9c5e-2a1d4e6f8b90",
"productOfferingIds": [
"string"
]
}
],
"simTypes": [
"PHYSICAL"
]
}StripeCheckoutContext
The Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
{
"clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
"connectedAccountId": "acct_1H8x2vLkdIwHu7ix",
"publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9"
}SubmitOrderRequest
Request to submit an order for fulfillment.
Depending on the order's requirements, payment intent, saved payment profile, or signing reference may be required.
In a fully managed flow, the order may be auto-submitted on successfully fulfilling all requirements (e.g. successful payment or signing).
externalobjectDetails of an external payment made outside the system. When provided, the order is considered paid and will bypass internal payment requirements.
Cannot be used together with paymentSessionId.
Show child attributes
receiptstringOptional human-readable description of the payment.
receiptstringuriOptional URL to a receipt or confirmation page for the payment.
referencestringmin length 1requiredReference or identifier from the external payment system.
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
*stringpaymentstringReference to completed payment profile session for zero-total orders requiring payment method setup.
paymentstringReference to completed payment session for orders requiring payment collection.
signingstringReference to completed signing session.
{
"externalPayment": {
"receiptDescription": "Payment via external billing system",
"receiptUrl": "https://external.example.com/receipts/123",
"reference": "ext-payment-ref-123"
},
"metadata": {
"propertyName": "string"
},
"paymentProfileSessionId": "b2c3d4e5-f6a7-8901-2345-6789abcdef01",
"paymentSessionId": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
"signingSessionId": "c3d4e5f6-a7b8-9012-3456-789abcdef012"
}Subscriber
The person or entity that uses a subscription's service (the end user), as opposed to the customer, who pays for it. For example, an employee using a company-paid phone plan.
addressobjectdeprecatedDeprecated. Use serviceAddress on each subscription instead.
The service address of the oldest subscription of the subscriber. A subscriber with two subscriptions can hold two service addresses, and this field shows only one.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
contactstringphonepersonal dataA phone number for reaching the subscriber, separate from the number their subscription provides.
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.
emailstringemailpersonal dataOptional email address of the subscriber.
namestringrequiredThe full name of the subscriber.
subscriberstringrequiredThe unique identifier of the subscriber.
subscriptionsarray of SubscriptionList of subscriptions associated with the subscriber.
Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.
Show child attributes
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
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.
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.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringmetadataobject 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
*stringmsisdnstringphonepersonal datarequiredThe 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.
pendingobjectpersonal dataA 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
msisdnstringphonepersonal datarequiredThe 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 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
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering 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
scheduledstringdateThe date when the pending status change is scheduled to occur.
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
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
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
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
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
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
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.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
simobjectrequiredSIM 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.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
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
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
namestringrequiredThe subscriber's full name.
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
updatedstringdate-timeDate and time when the subscriber was last updated.
subscriptionstringrequiredThe unique identifier for the subscription.
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.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"contactNumber": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"email": "john.doe@example.com",
"name": "John Doe",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"subscriptions": [
{
"activatedAt": "2024-01-15T10:30:00Z",
"barReasons": [
"MISSING_PAYMENT"
],
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"display": "(555) 123-4567",
"extensions": {
"propertyName": "string"
},
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"product": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"porting": {
"direction": "INBOUND",
"msisdn": "+15551234567",
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"referenceId": "crm-subscription-12345",
"serviceAddress": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"source": "SUBSCRIPTION"
},
"sim": {
"esim": true,
"iccid": "8901240197155182976",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"createdAt": "2024-01-15T10:30:00Z",
"email": "john.doe@example.com",
"name": "John Doe",
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"updatedAt": "2024-01-20T14:45:00Z"
},
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "CELL",
"updatedAt": "2024-01-15T10:30:00Z"
}
]
}Subscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
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.
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.
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringmetadataobject 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
*stringmsisdnstringphonepersonal datarequiredThe 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.
pendingobjectpersonal dataA 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
msisdnstringphonepersonal datarequiredThe 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 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
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
scheduledstringdaterequiredThe date when the pending product offering 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
scheduledstringdateThe date when the pending status change is scheduled to occur.
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
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
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
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
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
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
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.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
simobjectrequiredSIM 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.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
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
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
createdstringdate-timeDate and time when the subscriber was created.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
namestringrequiredThe subscriber's full name.
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
updatedstringdate-timeDate and time when the subscriber was last updated.
subscriptionstringrequiredThe unique identifier for the subscription.
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.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
{
"activatedAt": "2024-01-15T10:30:00Z",
"barReasons": [
"MISSING_PAYMENT"
],
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"display": "(555) 123-4567",
"extensions": {
"propertyName": "string"
},
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"product": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"porting": {
"direction": "INBOUND",
"msisdn": "+15551234567",
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"referenceId": "crm-subscription-12345",
"serviceAddress": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"source": "SUBSCRIPTION"
},
"sim": {
"esim": true,
"iccid": "8901240197155182976",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"createdAt": "2024-01-15T10:30:00Z",
"email": "john.doe@example.com",
"name": "John Doe",
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"updatedAt": "2024-01-20T14:45:00Z"
},
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "CELL",
"updatedAt": "2024-01-15T10:30:00Z"
}SubscriptionAction
A subscription operation and its execution state. Action payloads and internal task details are not exposed.
actionstringrequiredUnique identifier for this action.
applystringdate-timerequiredWhen the operation is scheduled to take effect.
createdstringdate-timerequiredWhen the action was created.
customerstringrequiredCustomer that owns the subscription.
executionstringdate-timeWhen execution ended, if it has finished.
executionstringdate-timeWhen execution began, if it has started.
scheduleenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
subscriptionstringrequiredSubscription affected by this action.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
updatedstringdate-timerequiredWhen the action was most recently updated.
{
"actionId": "string",
"applyAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-15T10:30:00Z",
"customerId": "string",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"scheduleMode": "ON_DEMAND",
"status": "PENDING",
"subscriptionId": "string",
"type": "ENABLE_VOWIFI",
"updatedAt": "2024-01-15T10:30:00Z"
}SubscriptionActionScheduleMode
How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
ExampleON_DEMAND
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
"ON_DEMAND"SubscriptionActionStatus
The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
ExamplePENDING
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
"PENDING"SubscriptionActionType
The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
ExampleENABLE_VOWIFI
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
"ENABLE_VOWIFI"SubscriptionAddon
An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan.
addedstringdate-timeThe date and time when the add-on was added to the subscription.
cancelledstringdate-timeThe date and time when the add-on was canceled (if applicable).
expiredstringdate-timeThe date and time when the add-on expired (if applicable).
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
licenseobjectEssential license information without sensitive details.
Show child attributes
activatedstringdate-timeWhen the license was activated.
assignedobjectrequiredThe entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.
Show child attributes
subscriptionstringDisplay name for the subscription (typically the phone number)
subscriptionstringrequiredThe unique identifier for the subscription
typeenum<string>requiredThe type of assignment
values
SUBSCRIPTION
customerobjectCustomer 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.
licensestringrequiredThe unique identifier for the license.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
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
typestringThe 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.
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
*stringpendingobjectA product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
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
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
scheduledstringdateThe date when the pending product offering change is scheduled to occur.
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
scheduledstringdateThe date when the pending status change is scheduled to occur.
statusenum<string>The status of an add-on on a subscription.
- PENDING: Add-on is scheduled but not yet active
- ACTIVE: Add-on is currently active and billable
- CANCELLED: Add-on has been cancelled and is no longer active
- EXPIRED: Add-on has expired and is no longer active
values
PENDINGACTIVECANCELLEDEXPIRED
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED- Cellular subscription at a fixed locationPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roamingPRODUCT_CATEGORY_VANITY_NUMBER_FORWARD- Vanity number that forwards callsPRODUCT_CATEGORY_VANITY_NUMBER_CELL- Vanity number on a cellular subscription
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addonPRODUCT_CATEGORY_ABROAD_EXTRA_DATA- Additional data package for roamingPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU- Data package for use outside the EUPRODUCT_CATEGORY_NETWORK_EXTENSIONS- Network feature addonPRODUCT_CATEGORY_VANITY_NUMBER- Vanity number addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
LICENSE categories (PBX):
PRODUCT_CATEGORY_PBX_USER_LEVEL- Level of a PBX user licensePRODUCT_CATEGORY_PBX_NUMBER- PBX phone numberPRODUCT_CATEGORY_PBX_MOBILE_NUMBER- PBX mobile numberPRODUCT_CATEGORY_PBX_LANDLINE_FORWARD- Forward from a landline numberPRODUCT_CATEGORY_PBX_SOFTPHONE- SoftphonePRODUCT_CATEGORY_PBX_STATISTICS- Call statisticsPRODUCT_CATEGORY_PBX_CALL_RECORDING- Call recordingPRODUCT_CATEGORY_PBX_VOICEMAIL- VoicemailPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS- Queue capacityPRODUCT_CATEGORY_PBX_ROUTE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_QUEUE- Call routesPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE,PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL- Call route features
Other categories:
PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER,PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
A caller must tolerate new values.
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXEDPRODUCT_CATEGORY_VANITY_NUMBER_FORWARDPRODUCT_CATEGORY_VANITY_NUMBER_CELLPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_ABROAD_EXTRA_DATAPRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EUPRODUCT_CATEGORY_NETWORK_EXTENSIONSPRODUCT_CATEGORY_VANITY_NUMBERPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARDPRODUCT_CATEGORY_PBX_USER_LEVELPRODUCT_CATEGORY_PBX_NUMBERPRODUCT_CATEGORY_PBX_MOBILE_NUMBERPRODUCT_CATEGORY_PBX_LANDLINE_FORWARDPRODUCT_CATEGORY_PBX_SOFTPHONEPRODUCT_CATEGORY_PBX_STATISTICSPRODUCT_CATEGORY_PBX_CALL_RECORDINGPRODUCT_CATEGORY_PBX_VOICEMAILPRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERSPRODUCT_CATEGORY_PBX_ROUTE_IVRPRODUCT_CATEGORY_PBX_ROUTE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVRPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUPPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUEPRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAILPRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNERPRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstringDescription of the product group in the requested locale.
internalstringInternal description of the product group for operational use only.
namestringrequiredName of the product group in the requested locale.
productstringrequiredUnique identifier for the product group.
imagestringuriURL to the image representing the product offering.
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
billingobjectHow often a recurring price is charged.
Show child attributes
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
referencestringmax length 255A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.
statusenum<string>requiredThe status of an add-on on a subscription.
- PENDING: Add-on is scheduled but not yet active
- ACTIVE: Add-on is currently active and billable
- CANCELLED: Add-on has been cancelled and is no longer active
- EXPIRED: Add-on has expired and is no longer active
values
PENDINGACTIVECANCELLEDEXPIRED
subscriptionstringrequiredThe unique identifier of the subscription add-on.
subscriptionstringrequiredThe unique identifier of the subscription this add-on belongs to.
updatedstringdate-timeThe date and time when the add-on was last updated.
{
"addedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"expiredAt": "2024-07-15T00:00:00Z",
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"license": {
"activatedAt": "2024-01-15T10:30:00Z",
"assignedTo": {
"subscriptionDisplay": "+1 (555) 123-4567",
"subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
"type": "SUBSCRIPTION"
},
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"status": "PENDING",
"type": "PBX_USER_LEVEL"
},
"metadata": {
"propertyName": "string"
},
"pendingProductOffering": {
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"scheduledAt": "2024-02-01"
},
"pendingStatus": {
"scheduledAt": "2024-02-01",
"status": "PENDING"
},
"productOffering": {
"group": {
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"internalDescription": "Core mobile offerings targeting consumer and business segments",
"name": "Mobile Plans",
"productOfferingGroupId": "mobile-plans"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"name": "Mobile Unlimited",
"price": {
"billingCycle": {
"interval": 1,
"period": "MONTHLY"
},
"bindingContract": {
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
},
"duration": {
"unit": "MONTHS",
"value": 3
}
},
"currency": "USD",
"currencyOptionsMinor": {
"propertyName": 1
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"includesTax": false,
"netPriceMinor": 2999,
"priceType": "ONE_TIME",
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
},
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"referenceId": "telna-package-12345",
"status": "PENDING",
"subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"updatedAt": "2024-01-20T09:00:00Z"
}SubscriptionAddonListItem
An add-on attached to a subscription, as returned inside subscription list responses. Carries the essentials for showing the add-on alongside its subscription; fetch the add-on individually for the full detail.
addedstringdate-timeThe date and time when the add-on was added to the subscription.
cancelledstringdate-timeThe date and time when the add-on was canceled (if applicable).
licensestringThe unique identifier of the license associated with this add-on (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
*stringproductstringThe unique identifier for the product offering group.
productstringrequiredThe unique identifier for the product offering.
referencestringmax length 255A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.
statusenum<string>requiredThe status of an add-on on a subscription.
- PENDING: Add-on is scheduled but not yet active
- ACTIVE: Add-on is currently active and billable
- CANCELLED: Add-on has been cancelled and is no longer active
- EXPIRED: Add-on has expired and is no longer active
values
PENDINGACTIVECANCELLEDEXPIRED
updatedstringdate-timeThe date and time when the add-on was last updated.
{
"addedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
"metadata": {
"propertyName": "string"
},
"productOfferingGroupId": "extra-data-packages",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"referenceId": "telna-package-12345",
"status": "PENDING",
"updatedAt": "2024-01-20T09:00:00Z"
}SubscriptionAddonStatus
The status of an add-on on a subscription.
- PENDING: Add-on is scheduled but not yet active
- ACTIVE: Add-on is currently active and billable
- CANCELLED: Add-on has been cancelled and is no longer active
- EXPIRED: Add-on has expired and is no longer active
values
PENDINGACTIVECANCELLEDEXPIRED
"PENDING"SubscriptionChangeLineItem
Line item that changes an existing subscription.
The changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item.
changeenum<string>requiredWhat this line item changes.
PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.
The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.
values
PLAN_CHANGESIM_CHANGE
linestringrequiredUnique identifier for this line item within the order.
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
*stringplanobjectThe plan change. Give this value only for changeType PLAN_CHANGE.
A change of the product of a subscription.
Show child attributes
productstringrequiredThe plan offering to change to. The platform refuses an offering in the SIM card category.
schedulestringdateEarliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.
simobjectThe SIM card change. Give this value only for changeType SIM_CHANGE.
A change of the SIM card of a subscription. The change carries a one-time price.
Show child attributes
productstringrequiredThe SIM card offering to change to. The offering must be in the SIM card category.
simobjectThe SIM card of the change.
The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect.
The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
esimbooleanrequiredWhether this line item uses eSIM technology.
iccidstringpersonal dataIntegrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.
This feature only applies to certain networks.
imeistringpersonal dataInternational Mobile Equipment Identity for eSIM activation.
Some networks require this to activate the eSIM.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriptionstringrequiredThe identifier of the existing subscription that this line item changes.
typeenum<string>requiredIdentifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.
values
SUBSCRIPTION_CHANGE
{
"changeType": "PLAN_CHANGE",
"lineItemId": "line-item-7",
"metadata": {
"propertyName": "string"
},
"planChange": {
"productOfferingId": "mobile-plan-premium"
},
"scheduleDate": "2024-02-01",
"simChange": {
"productOfferingId": "sim-card-replacement",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
}
},
"status": "PENDING",
"subscriptionId": "subscription-456",
"type": "SUBSCRIPTION_CHANGE"
}SubscriptionEsimProfile
The live eSIM profile status of a subscription's SIM, reported by the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device.
eidstringThe EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.
installedintegerThe number of times a device installed this profile. Absent when the network operator sets no limit.
laststringdate-timeWhen the last eUICC operation occurred for this profile.
maxintegerThe maximum number of times a device can install this profile. Absent when the network operator sets no limit.
statusenum<string>requiredThe installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.
values
AVAILABLEALLOCATEDLINKEDCONFIRMEDRELEASEDDOWNLOADEDINSTALLEDENABLEDDISABLEDERRORUNAVAILABLEDELETED
subscriptionstringrequiredThe unique identifier of the subscription this eSIM profile belongs to.
{
"eid": "89049032004008882600009B40002780",
"installedCount": 3,
"lastOperationAt": "2024-06-15T14:30:00Z",
"maxCount": 5,
"status": "AVAILABLE",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
}SubscriptionLineItem
Create a new subscription in this order. This will set up a new phone service for a customer with their chosen plan and phone number.
activatebooleanWhether the subscription waits for the subscriber to activate it rather than being activated on a date.
The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.
Cannot be combined with scheduleActivationAt.
displaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
*stringleasestringToken received when leasing a number. Required when an msisdn is provided from the number pool.
linestringrequiredUnique identifier for this line item within the order.
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
*stringmsisdnstringpersonal dataThe phone number for this subscription.
- Leave empty to have one assigned.
- When the number pool is available, you can choose a number from the pool and provide the leaseToken.
- When porting a number, provide the number and porting details.
portingobjectDetails needed to port in a number for this subscription.
Show child attributes
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
portingbooleanIf true, the number is a port-in.
productstringrequiredThe product offering to create a subscription for.
schedulestringdateDate when the subscription should be activated. Cannot be combined with activateOnDemand.
simobjectThe choice between eSIM and physical SIM plus related device details.
This value is optional while the order is a draft. You must give it before you submit the order.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
esimbooleanrequiredWhether this line item uses eSIM technology.
iccidstringpersonal dataIntegrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.
This feature only applies to certain networks.
imeistringpersonal dataInternational Mobile Equipment Identity for eSIM activation.
Some networks require this to activate the eSIM.
statusenum<string>deprecatedDeprecated. Use state on the order.
An order fulfills all its line items or none of them, so every line item of
an order reports what the order's own state already gives you.
The fulfillment status of an order line item.
An order fulfills all its line items or none of them. Thus the status follows the order state,
and each line item of one order has the same status. The status does not show when the network
provisions a subscription or an add-on. The order.updated event carries the order again when
the network provisions an entity of the order.
values
PENDINGRUNNINGCOMPLETEDFAILED
subscriberobjectThe person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.
Show child attributes
addressobjectThe address where the subscriber uses this subscription. In the US, this is the E911 address.
Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataContact email of the subscriber.
msisdnstringphonepersonal dataContact phone number of the subscriber. May be the same as the subscription's msisdn.
namestringName of the subscriber.
tempbooleanWhether to use a temporary number until the porting is completed.
If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.
Can only be used when porting in a number (i.e., when msisdn and porting details are provided).
typeenum<string>requiredIdentifies this line item as a new subscription purchase. Always SUBSCRIPTION.
values
SUBSCRIPTION
{
"activateOnDemand": true,
"display": "John Doe - Work phone",
"extensions": {
"propertyName": "string"
},
"leaseToken": "lease_8f3b1c2d4e5f6789",
"lineItemId": "line-item-1",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"porting": {
"details": {
"accountNumber": "987654321",
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"firstName": "John",
"lastName": "Doe",
"passcode": "123456"
}
},
"portingRequested": true,
"productOfferingId": "mobile-plan-basic",
"scheduleActivationAt": "2024-02-01",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
},
"status": "PENDING",
"subscriber": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "john.doe@example.com",
"msisdn": "+15551234567",
"name": "John Doe"
},
"tempNumber": true,
"type": "SUBSCRIPTION"
}SubscriptionListItem
Simplified subscription representation optimized for list operations. Use the detailed Subscription schema for individual subscription views.
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.
customerstringrequiredThe unique identifier for the customer who owns this subscription.
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.
msisdnstringpersonal datarequiredThe 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.
productstringrequiredThe unique identifier for the product offering associated with this subscription.
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
subscriberstringrequiredThe unique identifier for the subscriber associated with this subscription.
subscriptionstringrequiredThe unique identifier for the subscription.
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.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
{
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "PENDING",
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"type": "CELL",
"updatedAt": "2024-01-15T10:30:00Z"
}SubscriptionPlanChange
A change of the product of a subscription.
productstringrequiredThe plan offering to change to. The platform refuses an offering in the SIM card category.
{
"productOfferingId": "mobile-plan-premium"
}SubscriptionServiceAddress
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"source": "SUBSCRIPTION"
}SubscriptionSimChange
A change of the SIM card of a subscription. The change carries a one-time price.
productstringrequiredThe SIM card offering to change to. The offering must be in the SIM card category.
simobjectThe SIM card of the change.
The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect.
The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription.
The choice between eSIM and physical SIM plus related device details.
Show child attributes
esimbooleanrequiredWhether this line item uses eSIM technology.
iccidstringpersonal dataIntegrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.
This feature only applies to certain networks.
imeistringpersonal dataInternational Mobile Equipment Identity for eSIM activation.
Some networks require this to activate the eSIM.
{
"productOfferingId": "sim-card-replacement",
"sim": {
"esim": true,
"iccid": "8931440400000000000",
"imei": "356938035643809"
}
}SubscriptionStatus
Current stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
"PENDING"SubscriptionType
The kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
ExampleCELL
"CELL"TaxBreakdownItem
A single tax or fee contributing to the total tax on a charge, such as state sales tax or a regulatory fee.
amountintegerint64requiredThe amount charged for this tax component, in minor units of the currency of the transaction.
descriptionstringrequiredHuman-readable name of the tax or fee, suitable for display on invoices and receipts.
ratenumberdecimalThe tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.
{
"amountMinor": 240,
"description": "Sales Tax",
"rate": 8.25
}TechnologyCoverage
Coverage details for a single network technology (such as 4G or 5G) at a checked location.
availablebooleanrequiredWhether this technology is available at the checked location.
{
"available": true
}TokenResponse
OAuth2-compatible token response containing the access token for authenticating API requests.
accessstringrequiredJWT access token for authenticating API requests. Include in the Authorization header as "Bearer {accessToken}".
expiresintegerrequiredNumber of seconds until the access token expires.
tokenenum<string>requiredThe type of token issued. Always "Bearer" for JWT tokens.
values
Bearer
userstringThe unique identifier of the authenticated user.
{
"accessToken": "<access-token>",
"expiresIn": 604800,
"tokenType": "Bearer",
"userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}USPortOutPin
A PIN that a subscriber gives to a new carrier to move a US number away.
expiresstringdate-timerequiredWhen the PIN stops working.
pinstringpersonal datarequiredThe 6-digit port-out PIN. Treat it as a credential.
{
"expiresAt": "2024-01-15T10:30:00Z",
"pin": "string"
}USPortOutPinState
The US port-out state of a subscription.
activeobjectThe active PIN. It is absent when the subscription has no active PIN.
A PIN that a subscriber gives to a new carrier to move a US number away.
Show child attributes
expiresstringdate-timerequiredWhen the PIN stops working.
pinstringpersonal datarequiredThe 6-digit port-out PIN. Treat it as a credential.
portobjectPresent while the number is in its port-out protection period after activation. The subscription can get a PIN in this period, but a port-out request with the PIN fails.
The port-out protection of a new number. During the protection period, a new carrier cannot port out the number, even with a valid PIN. Support can open the number for port-out before the period ends.
Show child attributes
portablestringdateThe first day that a new carrier can port out the number. It is absent when the subscription has no activation date. Then only support can open the number for port-out.
portablebooleanrequiredFalse when the subscription cannot port out, for example during a binding period. The PIN is then hidden, and no PIN can be generated.
{
"activePin": {
"expiresAt": "2024-01-15T10:30:00Z",
"pin": "string"
},
"portOutProtection": {
"portableFrom": "2026-10-28"
},
"portable": true
}USPortOutProtection
The port-out protection of a new number. During the protection period, a new carrier cannot port out the number, even with a valid PIN. Support can open the number for port-out before the period ends.
portablestringdateThe first day that a new carrier can port out the number. It is absent when the subscription has no activation date. Then only support can open the number for port-out.
{
"portableFrom": "2026-10-28"
}UpdateCustomerRequest
The customer fields to change. Only provided fields are updated; omitted fields keep their current values.
billingobjectBilling details for the customer.
Show child attributes
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
autobooleanWhether to automatically pay invoices for this customer if a valid payment method is available.
currencystringThe currency for the customer billing.
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. Must be a valid payment profile owned by this customer. Set to null to disable automatic payments.
emailstringemailpersonal dataThe email address to send invoices to.
Required if billing method is EMAIL_INVOICE.
methodenum<string>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
contactobjectContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
identitystringpersonal dataA 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.
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
*stringnamestringThe 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.
preferredstringThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Give it only when it is different from the billing address. A customer with no shipping address gets a delivery at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
userarray of stringUser IDs to associate with this customer, in addition to those already associated.
Depending on the user's role they will either be a member of the customer or given access to manage it. To remove a user, use the remove-user endpoint instead.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"autoPay": false,
"currency": "USD",
"defaultPaymentProfileId": "m47ac10b-58cc-4372-a567-0e02b2c3d479",
"email": "billing@example.com",
"method": "E_INVOICE"
},
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"identity": "12-3456789",
"metadata": {
"propertyName": "string"
},
"name": "John Doe",
"preferredLocale": "en-US",
"shippingAddress": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"userIds": [
"string"
]
}UpdateOrderRequest
Request to update order details (excludes line items).
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
addressobjectThe billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.
The platform reads it for tax only when the customer holds no billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
emailstringemailpersonal dataBilling contact email.
namestringBilling contact name.
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
*stringcustomerone ofReference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer.
Show child attributes
customerstringrequiredThe customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.
authenticatedbooleanrequiredAlways true.
billingobjectBilling configuration and payment preferences for the new customer.
Show child attributes
contactobjectContact information for the new customer.
Show child attributes
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
identitystringpersonal dataA 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.
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
namestringrequiredName for the new customer.
preferredstringPreferred locale for the customer.
referencestringmax length 255Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.
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
*stringpromostringPromo code to apply to the order, or an empty string to remove the one it holds. Rejected with
internalCode 4119 when no promotion has that code, or when it is outside its validity
period.
shippingobjectShipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
userone ofThe person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order.
Show child attributes
userstringrequiredThe user's internal ID.
authenticatedbooleanrequiredAlways true.
emailstringemailpersonal datarequiredThe email the user logs in with and receives order confirmations on.
identitystringpersonal dataA 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.
addressobjectdeprecatedDeprecated. The platform does not store this address. A user is a sign-in
identity, and the address of the person belongs to the customer that pays.
Give the address in customer instead.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
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
msisdnstringphonepersonal dataThe user's phone number.
namestringrequiredThe user's full name.
{
"billing": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"email": "billing@example.com",
"name": "John Doe"
},
"consents": {
"marketing": "true",
"termsOfService": "true"
},
"customer": {
"customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"metadata": {
"propertyName": "string"
},
"promoCode": "STUDENT2024",
"shipping": {
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"instructions": "Leave at front door",
"msisdn": "+15551234567",
"name": "John Doe"
},
"user": {
"userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}UpdateSubscriberRequest
Request to update a subscriber's information.
addressobjectdeprecatedDeprecated. Use changeSubscriptionServiceAddress instead.
The service address of the mobile subscription of the subscriber. The request fails when the subscriber does not have exactly one mobile subscription.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
contactstringphonepersonal dataA phone number for reaching the subscriber, separate from the number their subscription provides.
emailstringemailpersonal dataThe email address of the subscriber.
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
*stringnamestringThe full name of the subscriber.
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"contactNumber": "+15551234567",
"email": "john.doe@example.com",
"metadata": {
"propertyName": "string"
},
"name": "John Doe"
}UpfrontPayment
Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
billingintegerrequiredHow many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.
discountobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
amountintegerint64requiredThe amount that comes off each billing period, in minor currency units.
durationobjectHow long the discount lasts. An UPFRONT_PAYMENT discount always gives a duration, and it
covers the billing cycles that the customer pays for in advance. The other two sources omit
the duration when the discount never stops. The discount then comes off every charge for as
long as the price is in effect. For a one-time price that is the single charge.
A length of time, expressed as a count of some unit.
Show child attributes
unitenum<string>requiredThe unit of time being counted. Currently only months are supported.
values
MONTHS
valueintegerrequiredHow many of the unit the duration lasts.
invoicingstringWhat the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own.
sourceenum<string>What the customer must do to get the discount:
STANDARDis given to every customer who orders the offering.BINDING_CONTRACTneeds the customer to commit for the contract's length.UPFRONT_PAYMENTneeds the customer to pay for several billing periods at once.
values
STANDARDBINDING_CONTRACTUPFRONT_PAYMENT
{
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"invoicingDescription": "Campaign discount",
"source": "STANDARD"
}
}Usage
Current usage statistics for a subscription, organized by service type (voice, SMS, MMS, data). Within each service type, usage is broken down into per-package allowance buckets: the base plan's included allowance plus any add-on packages, each reporting used, remaining, and total amounts. A service type is omitted entirely when the subscription has no allowances of that type.
dataobjectData usage across all scopes and packages.
Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad).
Show child attributes
nationalarray of UsageDataNationalPackageAllowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.
Show child attributes
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
namestringrequiredHuman-readable name of the package, as shown to end users.
rlahintegerint64RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.
rlahintegerint64The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.
rlahintegerint64Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageDataRoamingPackageAllowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.
Show child attributes
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
namestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
mmsobjectMMS usage across all scopes and packages.
MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).
Show child attributes
ildarray of UsageMmsPackageAllowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).
Show child attributes
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
mmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
nationalarray of UsageMmsPackageAllowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.
Show child attributes
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
mmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageMmsPackageAllowance buckets for multimedia messages sent while roaming abroad.
Show child attributes
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
mmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
smsobjectSMS usage across all scopes and packages.
SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).
Show child attributes
ildarray of UsageSmsPackageAllowance buckets for messages sent from the home country to foreign numbers (international long distance).
Show child attributes
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
namestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
nationalarray of UsageSmsPackageAllowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.
Show child attributes
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
namestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageSmsPackageAllowance buckets for messages sent while roaming abroad.
Show child attributes
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
namestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
updatedstringdate-timerequiredWhen the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet.
voiceobjectVoice call usage across all scopes and packages.
Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers).
Show child attributes
ildarray of UsageVoiceIldPackageInternational long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes.
Show child attributes
balanceintegerint64Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.
currencystringThree-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.
expirystringdateThe date the remaining balance expires and can no longer be used. Absent when the balance does not expire.
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
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this balance. Present only when the balance comes from an add-on.
nationalarray of UsageVoicePackageAllowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.
Show child attributes
callintegerint64requiredNumber of calls placed against this allowance.
callintegerint64requiredCall time still available in this allowance, in seconds.
callintegerint64requiredCall time consumed from this allowance so far, in seconds.
callintegerint64requiredThe full call time allowance of this package, in seconds.
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
namestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageVoicePackageAllowance buckets for calls made while roaming abroad.
Show child attributes
callintegerint64requiredNumber of calls placed against this allowance.
callintegerint64requiredCall time still available in this allowance, in seconds.
callintegerint64requiredCall time consumed from this allowance so far, in seconds.
callintegerint64requiredThe full call time allowance of this package, in seconds.
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
namestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"data": {
"national": [
{
"dataBytesRemaining": 7516192768,
"dataBytesTotal": 10737418240,
"dataBytesUsed": 3221225472,
"metadata": {
"propertyName": "string"
},
"name": "10GB National",
"rlahBytesRemaining": 4294967296,
"rlahBytesTotal": 5368709120,
"rlahBytesUsed": 1073741824,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"dataBytesRemaining": 4294967296,
"dataBytesTotal": 5368709120,
"dataBytesUsed": 1073741824,
"metadata": {
"propertyName": "string"
},
"name": "Asia 5GB Roaming",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
},
"mms": {
"ild": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"national": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
},
"sms": {
"ild": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"national": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
},
"updatedAt": "2024-01-15T10:30:00Z",
"voice": {
"ild": [
{
"balanceMinor": 1550,
"currency": "USD",
"expiryDate": "2025-12-31",
"metadata": {
"propertyName": "string"
},
"name": "ILD Top-up",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"national": [
{
"callCount": 15,
"callRemainingSeconds": 32400,
"callSeconds": 3600,
"callTotalSeconds": 36000,
"metadata": {
"propertyName": "string"
},
"name": "Unlimited National",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"callCount": 15,
"callRemainingSeconds": 32400,
"callSeconds": 3600,
"callTotalSeconds": 36000,
"metadata": {
"propertyName": "string"
},
"name": "Unlimited National",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
}
}UsageData
Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad).
nationalarray of UsageDataNationalPackageAllowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.
Show child attributes
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
rlahintegerint64RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.
rlahintegerint64The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.
rlahintegerint64Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageDataRoamingPackageAllowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.
Show child attributes
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"national": [
{
"dataBytesRemaining": 7516192768,
"dataBytesTotal": 10737418240,
"dataBytesUsed": 3221225472,
"metadata": {
"propertyName": "string"
},
"name": "10GB National",
"rlahBytesRemaining": 4294967296,
"rlahBytesTotal": 5368709120,
"rlahBytesUsed": 1073741824,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"dataBytesRemaining": 4294967296,
"dataBytesTotal": 5368709120,
"dataBytesUsed": 1073741824,
"metadata": {
"propertyName": "string"
},
"name": "Asia 5GB Roaming",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
}UsageDataNationalPackage
A single data allowance bucket for use in the home country — either the base plan's included data or a package granted by an add-on — reporting bytes used and remaining. Also carries the package's RLAH (Roam Like At Home) counters when part of the allowance can be used while roaming in RLAH regions (such as the EU/EEA) at no extra cost.
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
rlahintegerint64RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.
rlahintegerint64The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.
rlahintegerint64Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"dataBytesRemaining": 7516192768,
"dataBytesTotal": 10737418240,
"dataBytesUsed": 3221225472,
"metadata": {
"propertyName": "string"
},
"name": "10GB National",
"rlahBytesRemaining": 4294967296,
"rlahBytesTotal": 5368709120,
"rlahBytesUsed": 1073741824,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}UsageDataRoamingPackage
A single data allowance bucket for use while roaming abroad — from the base plan's roaming allowance or a dedicated roaming add-on — reporting bytes used and remaining.
dataintegerint64requiredData still available in this allowance, in bytes.
dataintegerint64requiredThe full data allowance of this package, in bytes.
dataintegerint64requiredData consumed from this allowance so far, in bytes.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"dataBytesRemaining": 4294967296,
"dataBytesTotal": 5368709120,
"dataBytesUsed": 1073741824,
"metadata": {
"propertyName": "string"
},
"name": "Asia 5GB Roaming",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}UsageMms
MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).
ildarray of UsageMmsPackageAllowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).
Show child attributes
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
*stringmmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
nationalarray of UsageMmsPackageAllowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.
Show child attributes
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
*stringmmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageMmsPackageAllowance buckets for multimedia messages sent while roaming abroad.
Show child attributes
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
*stringmmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"ild": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"national": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
}UsageMmsPackage
A single MMS allowance bucket — either the base plan's included multimedia message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain.
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
*stringmmsintegerint64requiredNumber of multimedia messages consumed from this allowance so far.
mmsintegerint64requiredNumber of multimedia messages still available in this allowance.
mmsintegerint64requiredThe full multimedia message allowance of this package.
namestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"metadata": {
"propertyName": "string"
},
"mmsCount": 10,
"mmsRemaining": 90,
"mmsTotal": 100,
"name": "100 MMS National",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}UsagePackageStatus
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
"ACTIVE"UsageSms
SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).
ildarray of UsageSmsPackageAllowance buckets for messages sent from the home country to foreign numbers (international long distance).
Show child attributes
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
nationalarray of UsageSmsPackageAllowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.
Show child attributes
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageSmsPackageAllowance buckets for messages sent while roaming abroad.
Show child attributes
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"ild": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"national": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
}UsageSmsPackage
A single SMS allowance bucket — either the base plan's included message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
smsintegerint64requiredNumber of messages consumed from this allowance so far.
smsintegerint64requiredNumber of messages still available in this allowance.
smsintegerint64requiredThe full message allowance of this package.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"metadata": {
"propertyName": "string"
},
"name": "500 SMS National",
"smsCount": 25,
"smsRemaining": 475,
"smsTotal": 500,
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}UsageVoice
Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers).
ildarray of UsageVoiceIldPackageInternational long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes.
Show child attributes
balanceintegerint64Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.
currencystringThree-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.
expirystringdateThe date the remaining balance expires and can no longer be used. Absent when the balance does not expire.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this balance. Present only when the balance comes from an add-on.
nationalarray of UsageVoicePackageAllowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.
Show child attributes
callintegerint64requiredNumber of calls placed against this allowance.
callintegerint64requiredCall time still available in this allowance, in seconds.
callintegerint64requiredCall time consumed from this allowance so far, in seconds.
callintegerint64requiredThe full call time allowance of this package, in seconds.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
roamingarray of UsageVoicePackageAllowance buckets for calls made while roaming abroad.
Show child attributes
callintegerint64requiredNumber of calls placed against this allowance.
callintegerint64requiredCall time still available in this allowance, in seconds.
callintegerint64requiredCall time consumed from this allowance so far, in seconds.
callintegerint64requiredThe full call time allowance of this package, in seconds.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"ild": [
{
"balanceMinor": 1550,
"currency": "USD",
"expiryDate": "2025-12-31",
"metadata": {
"propertyName": "string"
},
"name": "ILD Top-up",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
],
"national": [
{
"callCount": 15,
"callRemainingSeconds": 32400,
"callSeconds": 3600,
"callTotalSeconds": 36000,
"metadata": {
"propertyName": "string"
},
"name": "Unlimited National",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
],
"roaming": [
{
"callCount": 15,
"callRemainingSeconds": 32400,
"callSeconds": 3600,
"callTotalSeconds": 36000,
"metadata": {
"propertyName": "string"
},
"name": "Unlimited National",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}
]
}UsageVoiceIldPackage
An international long distance (ILD) calling balance. Unlike national and roaming allowances, ILD calling is prepaid as a monetary amount that is drawn down per call, rather than a bucket of minutes.
balanceintegerint64Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.
currencystringThree-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.
expirystringdateThe date the remaining balance expires and can no longer be used. Absent when the balance does not expire.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
subscriptionstringThe subscription add-on that granted this balance. Present only when the balance comes from an add-on.
{
"balanceMinor": 1550,
"currency": "USD",
"expiryDate": "2025-12-31",
"metadata": {
"propertyName": "string"
},
"name": "ILD Top-up",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}UsageVoicePackage
A single voice allowance bucket — either the base plan's included calling allowance or one granted by an add-on — reporting how much call time has been used and how much remains, in seconds.
callintegerint64requiredNumber of calls placed against this allowance.
callintegerint64requiredCall time still available in this allowance, in seconds.
callintegerint64requiredCall time consumed from this allowance so far, in seconds.
callintegerint64requiredThe full call time allowance of this package, in seconds.
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
*stringnamestringrequiredHuman-readable name of the package, as shown to end users.
statusenum<string>requiredThe status of this package.
Whether a usage package is currently consumable.
- ACTIVE: The package is in its validity window and usage draws from it
- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable
values
ACTIVENOT_ACTIVEEXPIRED
subscriptionstringThe subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.
validstringdate-timeStart of the period this allowance applies to.
validstringdate-timeEnd of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.
{
"callCount": 15,
"callRemainingSeconds": 32400,
"callSeconds": 3600,
"callTotalSeconds": 36000,
"metadata": {
"propertyName": "string"
},
"name": "Unlimited National",
"status": "ACTIVE",
"subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"validFrom": "2025-01-01T00:00:00Z",
"validTo": "2025-02-01T00:00:00Z"
}User
A person who can sign in and manage one or more customers' accounts.
Users are distinct from subscribers: a user administers customers and their services, while a subscriber is the end user of a subscription.
createdstringdate-timeDate and time when the user was created.
customersarray of EmbeddedCustomerThe customers this user is associated with. The user can sign in and act on behalf of each of these customers.
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.
emailstringemailpersonal dataThe user's email address. This is their sign-in identity — login verification codes are sent to it — and it is used to reach them when they are a customer's contact person.
identitystringpersonal dataA 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.
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
*stringmsisdnstringphonepersonal dataThe user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.
namestringrequiredThe user's full name, shown in account management and used when the user is listed as a customer's contact person.
referencestringmax length 255A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users or to create/retrieve users during order creation.
updatedstringdate-timeDate and time when the user was last updated.
userstringrequiredUnique identifier for the user.
{
"createdAt": "2024-01-15T10:30:00Z",
"customers": [
{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
}
],
"email": "john.doe@example.com",
"identity": "12-3456789",
"metadata": {
"propertyName": "string"
},
"msisdn": "+15551234567",
"name": "John Doe",
"referenceId": "hr-employee-98765",
"updatedAt": "2024-01-20T14:45:00Z",
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
}UserRole
The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
"MEMBER"ValidateAddressRequest
Request to validate an address.
addressobjectrequiredThe address to validate. The platform does not store it.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
purposeenum<string>default SERVICEWhat the address is for. The purpose selects the rules that the address must obey.
SERVICE: the address where a line is used. On a US brand, it is the emergency (E911) address of the line. The platform applies the rules of the network operator, and can refuse a PO box.POSTAL: an address that only gets post, for example the address that a SIM card goes to. The platform applies only the address format of the country that the brand serves, and accepts a PO box.
If you do not send a purpose, the platform uses SERVICE.
values
SERVICEPOSTAL
{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"purpose": "SERVICE"
}VerifyEmailLoginRequest
Request to verify an email login by providing the verification code sent to the email address.
codestringpattern ^[0-9]{6}$requiredThe 6-digit verification code sent to the email address.
emailstringemailpersonal datarequiredThe email address used to initiate the login.
noncestringrequiredThe nonce returned from the start login request.
{
"code": "123456",
"email": "john.doe@example.com",
"nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}