telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Schemas

Every request, response and webhook payload schema in the API.

StartEmailLoginRequest

Request to initiate an email-based login flow. A verification code will be sent to the provided email address.

emailstringemailrequired

The email address to send the verification code to.

StartEmailLoginRequest
{
  "email": "john.doe@example.com"
}

StartEmailLoginResponse

Response from initiating an email login. Contains the nonce needed for verification and timing information.

noncestringrequired

Token to reference this authentication request during verification.

expiresInintegerrequired

Number of seconds until the verification code expires.

createdAtstringdate-timerequired

When the authentication request was created.

expiresAtstringdate-timerequired

When the verification code will expire.

StartEmailLoginResponse
{
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expiresIn": 300,
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T10:35:00Z"
}

Any

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

string
number
boolean
propertyNameany

Any additional properties, passed through as given.

array of any
Any
"string"

Error

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Error
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "internalCode": "4009",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email",
      "suggestion": "string"
    }
  ],
  "hint": "Verify the customerId and try again.",
  "traceId": "cc4a73acca1bb07e0e54bd41f5ce1e7e",
  "spanId": "37cec694d3b99f0f"
}

VerifyEmailLoginRequest

Request to verify an email login by providing the verification code sent to the email address.

emailstringemailrequired

The email address used to initiate the login.

noncestringrequired

The nonce returned from the start login request.

codestringpattern ^[0-9]{6}$required

The 6-digit verification code sent to the email address.

VerifyEmailLoginRequest
{
  "email": "john.doe@example.com",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "code": "123456"
}

TokenResponse

OAuth2-compatible token response containing the access token for authenticating API requests.

accessTokenstringrequired

JWT access token for authenticating API requests. Include in the Authorization header as "Bearer {accessToken}".

tokenTypeenum<string>required

The type of token issued. Always "Bearer" for JWT tokens.

values

  • Bearer
expiresInintegerrequired

Number of seconds until the access token expires.

userIdstring

The unique identifier of the authenticated user.

TokenResponse
{
  "accessToken": "<access-token>",
  "tokenType": "Bearer",
  "expiresIn": 604800,
  "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

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.

string

Example12-3456789

Identity
"12-3456789"

EmbeddedCustomer

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

EmbeddedCustomer
{
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "name": "John Doe"
}

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
Metadata
{
  "propertyName": "string"
}

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.

userIdstringrequired

Unique identifier for the user.

namestringrequired

The user's full name, shown in account management and used when the user is listed as a customer's contact person.

emailstringemail

The user's email address. This is their sign-in identity — login verification codes are sent to it — and it is used to reach them when they are a customer's contact person.

msisdnstringphone

The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.

identitystring

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.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users or to create/retrieve users during order creation.

customersarray of EmbeddedCustomer

The customers this user is associated with. The user can sign in and act on behalf of each of these customers.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

createdAtstringdate-time

Date and time when the user was created.

updatedAtstringdate-time

Date and time when the user was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
User
{
  "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "msisdn": "+15551234567",
  "identity": "12-3456789",
  "referenceId": "hr-employee-98765",
  "customers": [
    {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "John Doe"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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.

nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

Pagination
{
  "nextCursor": "eyJvZmZzZXQiOjEwMH0"
}

CreateUserRequest

The details needed to create a user and associate them with a customer they can manage.

namestringrequired

The user's full name, shown in account management and used when the user is listed as a customer's contact person.

emailstringemailrequired

The user's email address. This becomes their sign-in identity — login verification codes are sent to it.

msisdnstringphone

The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.

roleenum<string>default MEMBER

The role of the user when assigned to a customer. Defaults to 'MEMBER' if not specified.

values

  • MEMBER
  • MANAGER
  • ADMIN
customerIdstringrequired

The unique identifier for the customer to whom the user will belong. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this user in their own systems. Must be unique per tenant. Use this field to look up users by your external identifier.

identitystring

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.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreateUserRequest
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "msisdn": "+15551234567",
  "role": "MEMBER",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "referenceId": "hr-employee-98765",
  "identity": "12-3456789",
  "metadata": {
    "propertyName": "string"
  }
}

UpdateUserRequest

The user fields to change. Only provided fields are updated; omitted fields keep their current values.

namestring

The user's full name, shown in account management and used when the user is listed as a customer's contact person.

emailstringemail

The user's email address. This is their sign-in identity — changing it changes where login verification codes are sent.

msisdnstringphone

The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UpdateUserRequest
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "msisdn": "+15551234567",
  "metadata": {
    "propertyName": "string"
  }
}

CustomerType

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

enum<string>

values

  • CONSUMER
  • BUSINESS
CustomerType
"CONSUMER"

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.

enum<string>

values

  • E_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
CustomerBillingMethod
"E_INVOICE"

Address

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

Address
{
  "street1": "500 S Main St",
  "street2": "Apt 1",
  "city": "Natick",
  "zip": "01701",
  "country": "US",
  "state": "CA",
  "region": "Ontario",
  "attention": "John Doe"
}

Currency

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

string

ExampleUSD

Currency
"USD"

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.

enum<string>

values

  • MEMBER
  • MANAGER
  • ADMIN
UserRole
"MEMBER"

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.

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

  • MEMBER
  • MANAGER
  • ADMIN
EmbeddedCustomerUser
{
  "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "name": "John Doe",
  "role": "MEMBER"
}

Shipping

Shipping information for order fulfillment. Only required if the order contains shippable items.

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

Shipping
{
  "name": "John Doe",
  "msisdn": "+15551234567",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "instructions": "Leave at front door"
}

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.

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.

identitystring

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.

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.

contactobjectrequired

Contact details for the customer.

Show child attributes
emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes
methodenum<string>required

How invoices should be delivered to the customer.

How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.

values

  • E_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.

usersarray of EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes
userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

  • MEMBER
  • MANAGER
  • ADMIN
contactPersonobject

The primary contact person for the customer.

A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.

Show child attributes
userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

  • MEMBER
  • MANAGER
  • ADMIN
shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes
namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
Customer
{
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "customerType": "CONSUMER",
  "name": "John Doe",
  "identity": "12-3456789",
  "preferredLocale": "en-US",
  "humanReadableId": "29A-BY3Z-X78",
  "referenceId": "crm-customer-12345",
  "contact": {
    "email": "john.doe@example.com",
    "msisdn": "+15551234567"
  },
  "billing": {
    "method": "E_INVOICE",
    "email": "billing@company.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "currency": "USD",
    "defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
    "autoPay": true
  },
  "users": [
    {
      "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
      "name": "John Doe",
      "role": "MEMBER"
    }
  ],
  "contactPerson": {
    "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
    "name": "John Doe",
    "role": "MEMBER"
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "instructions": "Leave at front door"
  },
  "metadata": {
    "propertyName": "string"
  }
}

CreateCustomerRequest

The details needed to create a customer: who they are, how to reach them, how they should be billed, and which users can manage the account.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.

identitystring

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.

referenceIdstringmax length 255

Optional reference ID to assign to the customer. Must be unique per tenant.

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

contactobjectrequired

Contact details for the customer.

Show child attributes
emailstringemailrequired

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobjectrequired

Billing configuration and payment preferences for the customer.

Show child attributes
methodenum<string>required

How invoices should be delivered to the customer.

How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.

values

  • E_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Used for invoicing and tax calculation.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer.

autoPaybooleandefault false

Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.

userIdsarray of stringrequired

List of user IDs to associate with this customer.

Depending on the user's role they will either be a member of the customer or given access to manage it.

contactPersonUserIdstringrequired

The user ID of the contact person for this customer.

This user will be set as the primary contact for the customer and will receive important notifications.

shippingobject

The default shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes
namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreateCustomerRequest
{
  "customerType": "CONSUMER",
  "name": "John Doe",
  "identity": "12-3456789",
  "referenceId": "crm-customer-12345",
  "preferredLocale": "en-US",
  "contact": {
    "email": "john.doe@example.com",
    "msisdn": "+15551234567"
  },
  "billing": {
    "method": "E_INVOICE",
    "email": "billing@company.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "currency": "USD",
    "defaultPaymentProfileId": "l47ac10b-58cc-4372-a567-0e02b2c3d479",
    "autoPay": true
  },
  "userIds": [
    "string"
  ],
  "contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "instructions": "Leave at front door"
  },
  "metadata": {
    "propertyName": "string"
  }
}

UpdateCustomerRequest

The customer fields to change. Only provided fields are updated; omitted fields keep their current values.

namestring

The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.

identitystring

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.

preferredLocalestring

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

contactobject

Contact details for the customer.

Show child attributes
emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing details for the customer.

Show child attributes
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_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
emailstringemail

The email address to send invoices to.

Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer.

Required if billing method is PAPER_INVOICE.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

currencystring

The currency for the customer billing.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. Must be a valid payment profile owned by this customer. Set to null to disable automatic payments.

autoPayboolean

Whether to automatically pay invoices for this customer if a valid payment method is available.

userIdsarray of string

User IDs to associate with this customer, in addition to those already associated.

Depending on the user's role they will either be a member of the customer or given access to manage it. To remove a user, use the remove-user endpoint instead.

shippingAddressobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UpdateCustomerRequest
{
  "name": "John Doe",
  "identity": "12-3456789",
  "preferredLocale": "en-US",
  "contact": {
    "email": "john.doe@example.com",
    "msisdn": "+15551234567"
  },
  "billing": {
    "method": "E_INVOICE",
    "email": "billing@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "currency": "USD",
    "defaultPaymentProfileId": "m47ac10b-58cc-4372-a567-0e02b2c3d479",
    "autoPay": false
  },
  "userIds": [
    "string"
  ],
  "shippingAddress": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "metadata": {
    "propertyName": "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 subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product
enum<string>

ExamplePRODUCT_CATEGORY_SUBSCRIPTION_CELL

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
ProductCategory
"PRODUCT_CATEGORY_SUBSCRIPTION_CELL"

ProductOfferingGroup

A product group organizes related product offerings.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

ProductOfferingGroup
{
  "productOfferingGroupId": "mobile-plans",
  "name": "Mobile Plans",
  "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
  "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
  "internalDescription": "Core mobile offerings targeting consumer and business segments"
}

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
enum<string>

ExampleSUBSCRIPTION

values

  • SUBSCRIPTION
  • SUBSCRIPTION_ADDON
  • LICENSE
  • EXTERNAL_PRODUCT
ProductType
"SUBSCRIPTION"

EmbeddedProduct

Embedded representation of a product.

productIdstringrequired

The unique identifier for the product.

internalNamestringrequired

The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.

typeenum<string>required

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

values

  • SUBSCRIPTION
  • SUBSCRIPTION_ADDON
  • LICENSE
  • EXTERNAL_PRODUCT
categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
networkProviderIdstring

The unique identifier for the network provider.

featuresobject

The features included with the product, if any. Typically used for telecom products.

Show child attributes
dataMbnumber

Megabytes of data included with the product. Present for cellular, data, and travel eSIM products.

includedCallSecondsinteger

Outbound call seconds included with the product. Present for cellular subscription categories.

includedSmsinteger

Number of SMS messages included with the product. Present for cellular subscription categories.

validityDaysinteger

Number of days the product is valid for. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

countriesarray of string

ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the countries query parameter on list endpoints to filter by coverage.

regionsarray of string

Named regions covered by the product. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the regions query parameter on list endpoints to filter by coverage.

activationTypeenum<string>

How the travel eSIM package activates. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

values

  • INSTANT
  • FIRST_USE
EmbeddedProduct
{
  "productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
  "internalName": "us-mobile-unlimited-5gb",
  "type": "SUBSCRIPTION",
  "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
  "networkProviderId": "tmobile-us",
  "features": {
    "dataMb": 2048,
    "includedCallSeconds": 1000,
    "includedSms": 500,
    "validityDays": 30,
    "countries": [
      "USA",
      "CAN",
      "MEX"
    ],
    "regions": [
      "NORTH_AMERICA"
    ],
    "activationType": "INSTANT"
  }
}

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).
enum<string>

values

  • ONE_TIME
  • RECURRING
PriceType
"ONE_TIME"

Duration

A length of time, expressed as a count of some unit.

unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

Duration
{
  "unit": "MONTHS",
  "value": 3
}

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.

amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

PriceDiscount
{
  "amountMinor": 500,
  "duration": {
    "unit": "MONTHS",
    "value": 3
  }
}

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.

durationobjectrequired

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

BindingContract
{
  "duration": {
    "unit": "MONTHS",
    "value": 3
  },
  "discount": {
    "amountMinor": 500,
    "duration": {
      "unit": "MONTHS",
      "value": 3
    }
  }
}

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.

billingCyclesintegerrequired

How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

UpfrontPayment
{
  "billingCycles": 3,
  "discount": {
    "amountMinor": 500,
    "duration": {
      "unit": "MONTHS",
      "value": 3
    }
  }
}

BillingCycle

How often a recurring price is charged.

periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

BillingCycle
{
  "period": "MONTHLY",
  "interval": 1
}

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.

discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
durationobjectrequired

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
unitenum<string>required

The unit of time being counted. Currently only months are supported.

values

  • MONTHS
valueintegerrequired

How many of the unit the duration lasts.

customUpfrontPaymentobject

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.

Show child attributes
billingCyclesintegerrequired

How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
*numberdecimal
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
*integerint64
Price
{
  "discount": 9.99,
  "discountMinor": 1,
  "netPrice": 29.99,
  "netPriceMinor": 2999,
  "currency": "USD",
  "priceType": "ONE_TIME",
  "boundMonths": 12,
  "bindingContract": {
    "duration": {
      "unit": "MONTHS",
      "value": 3
    },
    "discount": {
      "amountMinor": 500,
      "duration": {
        "unit": "MONTHS",
        "value": 3
      }
    }
  },
  "standardDiscount": {
    "amountMinor": 500,
    "duration": {
      "unit": "MONTHS",
      "value": 3
    }
  },
  "customUpfrontPayment": {
    "billingCycles": 3,
    "discount": {
      "amountMinor": 500,
      "duration": {
        "unit": "MONTHS",
        "value": 3
      }
    }
  },
  "billingCycle": {
    "period": "MONTHLY",
    "interval": 1
  },
  "currencyOptions": {
    "propertyName": 9.99
  },
  "currencyOptionsMinor": {
    "propertyName": 1
  }
}

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.

productOfferingIdstringrequired

Unique identifier for the product offering.

statusenum<string>required

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

  • AVAILABLE
  • ARCHIVED
namestringrequired

Name of the product offering.

descriptionstring

Description of the product offering.

richContentstring

Rich HTML content with detailed information about the product offering.

productobjectrequired

Embedded representation of a product.

Show child attributes
productIdstringrequired

The unique identifier for the product.

internalNamestringrequired

The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.

typeenum<string>required

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

values

  • SUBSCRIPTION
  • SUBSCRIPTION_ADDON
  • LICENSE
  • EXTERNAL_PRODUCT
categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
networkProviderIdstring

The unique identifier for the network provider.

featuresobject

The features included with the product, if any. Typically used for telecom products.

Show child attributes
dataMbnumber

Megabytes of data included with the product. Present for cellular, data, and travel eSIM products.

includedCallSecondsinteger

Outbound call seconds included with the product. Present for cellular subscription categories.

includedSmsinteger

Number of SMS messages included with the product. Present for cellular subscription categories.

validityDaysinteger

Number of days the product is valid for. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

countriesarray of string

ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the countries query parameter on list endpoints to filter by coverage.

regionsarray of string

Named regions covered by the product. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE). Use the regions query parameter on list endpoints to filter by coverage.

activationTypeenum<string>

How the travel eSIM package activates. Present for travel eSIM packages (TRAVEL_ESIM_PACKAGE).

values

  • INSTANT
  • FIRST_USE
priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
durationobjectrequired

A length of time, expressed as a count of some unit.

Show child attributes
discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
customUpfrontPaymentobject

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.

Show child attributes
billingCyclesintegerrequired

How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
*numberdecimal
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
*integerint64
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
addonCategoriesarray of ProductCategory

List of product categories this addon is applicable for. Only populated when type is SUBSCRIPTION_ADDON. For example, a TRAVEL_ESIM_PACKAGE addon might be applicable to TRAVEL_ESIM subscriptions.

internalDescriptionstring

Internal description of the product offering for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ProductOffering
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "AVAILABLE",
  "name": "Seamless 10GB",
  "description": "Basic mobile plan with 5GB data and unlimited calls",
  "richContent": "<h3>Features</h3><ul><li>5GB monthly data</li><li>Unlimited calls & texts</li><li>No setup fees</li></ul>",
  "product": {
    "productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
    "internalName": "us-mobile-unlimited-5gb",
    "type": "SUBSCRIPTION",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "networkProviderId": "tmobile-us",
    "features": {
      "dataMb": 2048,
      "includedCallSeconds": 1000,
      "includedSms": 500,
      "validityDays": 30,
      "countries": [
        "USA",
        "CAN",
        "MEX"
      ],
      "regions": [
        "NORTH_AMERICA"
      ],
      "activationType": "INSTANT"
    }
  },
  "price": {
    "discount": 9.99,
    "discountMinor": 1,
    "netPrice": 29.99,
    "netPriceMinor": 2999,
    "currency": "USD",
    "priceType": "ONE_TIME",
    "boundMonths": 12,
    "bindingContract": {
      "duration": {
        "unit": "MONTHS",
        "value": 3
      },
      "discount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      }
    },
    "standardDiscount": {
      "amountMinor": 500,
      "duration": {
        "unit": "MONTHS",
        "value": 3
      }
    },
    "customUpfrontPayment": {
      "billingCycles": 3,
      "discount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      }
    },
    "billingCycle": {
      "period": "MONTHLY",
      "interval": 1
    },
    "currencyOptions": {
      "propertyName": 9.99
    },
    "currencyOptionsMinor": {
      "propertyName": 1
    }
  },
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "customerType": "CONSUMER",
  "addonCategories": [
    "PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
  ],
  "internalDescription": "seamless_cell_10gb_us",
  "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
  "metadata": {
    "propertyName": "string"
  }
}

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
enum<string>

values

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
SubscriptionStatus
"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.

string

ExampleCELL

SubscriptionType
"CELL"

EmbeddedProductOffering

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
durationobjectrequired

A length of time, expressed as a count of some unit.

Show child attributes
discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
amountMinorintegerint64required

The amount that comes off each billing period, in minor currency units.

durationobject

How long the discount lasts. Omitted when it never stops: the discount then comes off every charge for as long as the price is in effect, which for a one-time price means the single charge.

A length of time, expressed as a count of some unit.

Show child attributes
customUpfrontPaymentobject

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.

Show child attributes
billingCyclesintegerrequired

How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months.

discountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
*numberdecimal
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
*integerint64
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

EmbeddedProductOffering
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Mobile Unlimited",
  "price": {
    "discount": 9.99,
    "discountMinor": 1,
    "netPrice": 29.99,
    "netPriceMinor": 2999,
    "currency": "USD",
    "priceType": "ONE_TIME",
    "boundMonths": 12,
    "bindingContract": {
      "duration": {
        "unit": "MONTHS",
        "value": 3
      },
      "discount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      }
    },
    "standardDiscount": {
      "amountMinor": 500,
      "duration": {
        "unit": "MONTHS",
        "value": 3
      }
    },
    "customUpfrontPayment": {
      "billingCycles": 3,
      "discount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      }
    },
    "billingCycle": {
      "period": "MONTHLY",
      "interval": 1
    },
    "currencyOptions": {
      "propertyName": 9.99
    },
    "currencyOptionsMinor": {
      "propertyName": 1
    }
  },
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}

EmbeddedSubscriber

The person who uses the service on a subscription, as distinct from the customer who pays for it.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

EmbeddedSubscriber
{
  "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

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
enum<string>

values

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
PortingStatus
"PENDING"

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.

enum<string>

values

  • INBOUND
  • OUTBOUND
PortingDirection
"INBOUND"

EmbeddedPorting

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
directionenum<string>required

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

  • INBOUND
  • OUTBOUND
scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

EmbeddedPorting
{
  "msisdn": "+15551234567",
  "status": "PENDING",
  "direction": "INBOUND",
  "scheduledAt": "2024-02-01"
}

Subscription

A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.

subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
typestringrequired

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.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
customUpfrontPaymentobject

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.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes
msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes
statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

Show child attributes
msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
directionenum<string>required

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

  • INBOUND
  • OUTBOUND
scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
Subscription
{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "crm-subscription-12345",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "discount": 9.99,
      "discountMinor": 1,
      "netPrice": 29.99,
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "boundMonths": 12,
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {
        "propertyName": 9.99
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "subscriber": {
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "extensions": {
    "propertyName": "string"
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8901240197155182976"
  },
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "discount": 9.99,
        "discountMinor": 1,
        "netPrice": 29.99,
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "boundMonths": 12,
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {
          "propertyName": 9.99
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "porting": {
    "msisdn": "+15551234567",
    "status": "PENDING",
    "direction": "INBOUND",
    "scheduledAt": "2024-02-01"
  },
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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.

accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

PortingDetailsUS
{
  "accountNumber": "987654321",
  "passcode": "123456",
  "firstName": "John",
  "lastName": "Doe",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

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.

identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

PortingDetailsSweden
{
  "identity": "199001011234"
}

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.

accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

PortingDetails
{
  "accountNumber": "987654321",
  "passcode": "123456",
  "firstName": "John",
  "lastName": "Doe",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

SubscriptionActivation

Configuration and details required to activate a subscription in the telecommunications network.

This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services.

msisdnstring

The phone number for this subscription.

  • Leave empty to have a number automatically assigned from the available pool
  • Provide a specific number when using a leased number from the number pool
  • Provide the number to be ported when transferring from another carrier
leaseTokenstring

Token received when leasing a number from the available number pool.

Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers.

portingobject

Details required to port (transfer) an existing phone number from another carrier.

Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements.

Show child attributes
detailsone ofrequired

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.

Show child attributes
simobjectrequired

SIM card technology and configuration for this subscription.

Show child attributes
esimbooleanrequired

Whether this subscription uses eSIM (embedded SIM) technology.

  • true: Digital eSIM profile will be provisioned to the device
  • false: Physical SIM card will be used
iccidstring

Integrated Circuit Card Identifier (ICCID) of an existing SIM card.

Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM.

deliveryAddressobject

Physical address to ship the SIM card to (for physical SIM only).

If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

SubscriptionActivation
{
  "msisdn": "+15551234567",
  "leaseToken": "lease_abc123def456",
  "porting": {
    "details": {
      "accountNumber": "987654321",
      "passcode": "123456",
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "street1": "500 S Main St",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      }
    }
  },
  "sim": {
    "esim": true,
    "iccid": "8931440400000000000"
  },
  "deliveryAddress": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

CreateSubscriptionRequest

Create a new subscription for a customer.

Activation Options:

  1. Immediate activation: Provide activation data without scheduleActivationAt
  2. Scheduled activation: Provide activation data with scheduleActivationAt for future activation
  3. Shell subscription: Omit activation data to create a subscription that will be activated later

When to use shell subscriptions:

  • When activation details are not yet available (e.g., waiting for SIM card delivery)
  • When activation requires additional approval or processing
  • When bulk-creating subscriptions for later activation

Note: This endpoint is disabled when Seamless OS manages billing. In that case, subscriptions are created through orders.

productOfferingIdstringrequired

The unique identifier for the product offering to subscribe to.

This controls what type of subscription is being created.

customerIdstringrequired

The identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer.

referenceIdstringmax length 255

Optional reference ID to assign to the subscription. Must be unique per tenant. Once set, this value can be used in place of the subscriptionId in path parameters and request bodies across the API.

activationobject

Everything needed to bring the subscription online in the mobile network: the phone number (a specific number, a leased number, or empty for automatic assignment), the SIM configuration (eSIM or physical SIM), and optional porting details when the subscriber keeps their existing number from another carrier.

When to provide:

  • Provide activation details to have the subscription provisioned in the network — immediately, or on the date given in scheduleActivationAt
  • Omit to create a "shell" subscription that stays in PENDING status until you activate it later via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are not yet known
Show child attributes
msisdnstring

The phone number for this subscription.

  • Leave empty to have a number automatically assigned from the available pool
  • Provide a specific number when using a leased number from the number pool
  • Provide the number to be ported when transferring from another carrier
leaseTokenstring

Token received when leasing a number from the available number pool.

Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers.

portingobject

Details required to port (transfer) an existing phone number from another carrier.

Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements.

Show child attributes
detailsone ofrequired

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.

Show child attributes
simobjectrequired

SIM card technology and configuration for this subscription.

Show child attributes
esimbooleanrequired

Whether this subscription uses eSIM (embedded SIM) technology.

  • true: Digital eSIM profile will be provisioned to the device
  • false: Physical SIM card will be used
iccidstring

Integrated Circuit Card Identifier (ICCID) of an existing SIM card.

Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM.

deliveryAddressobject

Physical address to ship the SIM card to (for physical SIM only).

If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

scheduleActivationAtstringdate

Date when the subscription should be activated in the network.

Only applicable when activation data is provided. If omitted, activation will be immediate or as soon as network resources are available.

Note: Network availability and porting timelines may affect the exact activation time. This date is a preference, not a guarantee.

extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
*string
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobjectrequired

Subscriber details for this subscription.

Show child attributes
namestringrequired

The full name of the subscriber.

emailstringemail

The email address of the subscriber.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreateSubscriptionRequest
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "referenceId": "crm-subscription-12345",
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000"
    },
    "deliveryAddress": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "scheduleActivationAt": "2024-01-15",
  "extensions": {
    "propertyName": "string"
  },
  "display": "John's work phone",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "metadata": {
      "propertyName": "string"
    }
  },
  "metadata": {
    "propertyName": "string"
  }
}

ActivateSubscriptionRequest

Request to activate a pending subscription in the telecommunications network.

Use this endpoint to activate subscriptions that were created as "shells" without initial activation data, or to activate subscriptions that are in a state where network activation is needed.

Activation timing:

  • Omit scheduleActivationAt for immediate activation (or as soon as network resources are available)
  • Provide scheduleActivationAt to schedule activation for a future date
activationobjectrequired

Complete activation configuration required to bring the subscription online in the network.

This includes the phone number assignment, SIM card details, and any number porting information.

Configuration and details required to activate a subscription in the telecommunications network.

This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services.

Show child attributes
msisdnstring

The phone number for this subscription.

  • Leave empty to have a number automatically assigned from the available pool
  • Provide a specific number when using a leased number from the number pool
  • Provide the number to be ported when transferring from another carrier
leaseTokenstring

Token received when leasing a number from the available number pool.

Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers.

portingobject

Details required to port (transfer) an existing phone number from another carrier.

Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements.

Show child attributes
detailsone ofrequired

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.

Show child attributes
simobjectrequired

SIM card technology and configuration for this subscription.

Show child attributes
esimbooleanrequired

Whether this subscription uses eSIM (embedded SIM) technology.

  • true: Digital eSIM profile will be provisioned to the device
  • false: Physical SIM card will be used
iccidstring

Integrated Circuit Card Identifier (ICCID) of an existing SIM card.

Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM.

deliveryAddressobject

Physical address to ship the SIM card to (for physical SIM only).

If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

scheduleActivationAtstringdate

Date when the subscription should be scheduled for activation.

If not provided, activation will be immediate or as soon as possible based on network availability.

Note: Network availability and porting timelines may affect exact timing. This date is considered a preference, not a guarantee. The actual activation may occur on or after this date.

ActivateSubscriptionRequest
{
  "activation": {
    "msisdn": "+15551234567",
    "leaseToken": "lease_abc123def456",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000"
    },
    "deliveryAddress": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "scheduleActivationAt": "2025-01-01"
}

Porting

A request to transfer (port) a phone number between carriers, either into this platform from the subscriber's previous carrier or out to another carrier. Tracks the number, the transfer's progress, and the ownership details required by the carriers involved.

msisdnstringrequired

The phone number to be ported, in E.164 format.

statusenum<string>required

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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
directionenum<string>required

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

  • INBOUND
  • OUTBOUND
scheduledAtstringdate

The date when the porting is scheduled to occur.

detailsone ofrequired

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.

Show child attributes
accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

updatedAtstringdate-time

The timestamp of the last update to the porting request.

createdAtstringdate-timerequired

The timestamp when the porting request was created.

Porting
{
  "msisdn": "+15551234567",
  "status": "PENDING",
  "direction": "INBOUND",
  "scheduledAt": "2024-02-01",
  "details": {
    "accountNumber": "987654321",
    "passcode": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "updatedAt": "2024-01-20T09:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

UpdatePortingRequest

Request to correct or complete the porting details of a subscription's in-progress port-in, for example after the losing carrier rejected the transfer because the owner details did not match.

detailsone ofrequired

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.

Show child attributes
accountNumberstring

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

passcodestring

The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.

If not provided here, must be provided in the future for activation on-demand.

firstNamestringrequired

The first name of the account holder at the current provider.

lastNamestringrequired

The last name of the account holder at the current provider.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
identitystringrequired

The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.

UpdatePortingRequest
{
  "details": {
    "accountNumber": "987654321",
    "passcode": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  }
}

ChangeSubscriptionProductOfferingRequest

Request to change the product offering of a subscription.

productOfferingIdstringrequired

The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to.

scheduledAtstringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ChangeSubscriptionProductOfferingRequest
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}

ProductOfferingChangeSchedule

The schedule type for when a product offering change can take effect.

  • INSTANT: Change takes effect immediately
  • FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month
  • NEXT_RENEWAL_DAY: Change takes effect on the next renewal date
  • NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day
enum<string>

values

  • INSTANT
  • FIRST_OF_NEXT_MONTH
  • NEXT_RENEWAL_DAY
  • NEXT_PAYMENT_DAY
ProductOfferingChangeSchedule
"INSTANT"

ProductOfferingOption

A product offering option available for subscription changes with scheduling information.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
customUpfrontPaymentobject

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.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

changeScheduleenum<string>required

The schedule type for when a product offering change can take effect.

  • INSTANT: Change takes effect immediately
  • FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month
  • NEXT_RENEWAL_DAY: Change takes effect on the next renewal date
  • NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day

values

  • INSTANT
  • FIRST_OF_NEXT_MONTH
  • NEXT_RENEWAL_DAY
  • NEXT_PAYMENT_DAY
changeScheduleDatestringdaterequired

The date when the product offering change can take effect.

ProductOfferingOption
{
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "discount": 9.99,
      "discountMinor": 1,
      "netPrice": 29.99,
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "boundMonths": 12,
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {
        "propertyName": 9.99
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "changeSchedule": "INSTANT",
  "changeScheduleDate": "2024-02-01"
}

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
enum<string>

values

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
SubscriptionAddonStatus
"PENDING"

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
enum<string>

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
LicenseStatus
"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.

string

ExamplePBX_USER_LEVEL

LicenseType
"PBX_USER_LEVEL"

EmbeddedAssignedTo

Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.

typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

EmbeddedAssignedTo
{
  "type": "SUBSCRIPTION",
  "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
  "subscriptionDisplay": "+1 (555) 123-4567"
}

EmbeddedLicense

Essential license information without sensitive details.

licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

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.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
customUpfrontPaymentobject

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.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

assignedToone ofrequired

Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

customerobject

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

activatedAtstringdate-time

When the license was activated.

EmbeddedLicense
{
  "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
  "status": "PENDING",
  "type": "PBX_USER_LEVEL",
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "discount": 9.99,
      "discountMinor": 1,
      "netPrice": 29.99,
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "boundMonths": 12,
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {
        "propertyName": 9.99
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "assignedTo": {
    "type": "SUBSCRIPTION",
    "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
    "subscriptionDisplay": "+1 (555) 123-4567"
  },
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "activatedAt": "2024-01-15T10:30:00Z"
}

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.

subscriptionAddonIdstringrequired

The unique identifier of the subscription add-on.

subscriptionIdstringrequired

The unique identifier of the subscription this add-on belongs to.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
customUpfrontPaymentobject

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.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

licenseobject

Essential license information without sensitive details.

Show child attributes
licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestring

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.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

assignedToone ofrequired

Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

customerobject

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

activatedAtstringdate-time

When the license was activated.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>

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

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

scheduledAtstringdate

The date when the pending product offering change is scheduled to occur.

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

expiredAtstringdate-time

The date and time when the add-on expired (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
SubscriptionAddon
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "referenceId": "telna-package-12345",
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "discount": 9.99,
      "discountMinor": 1,
      "netPrice": 29.99,
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "boundMonths": 12,
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {
        "propertyName": 9.99
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "status": "PENDING",
  "group": {
    "productOfferingGroupId": "mobile-plans",
    "name": "Mobile Plans",
    "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
    "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
    "internalDescription": "Core mobile offerings targeting consumer and business segments"
  },
  "license": {
    "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
    "status": "PENDING",
    "type": "PBX_USER_LEVEL",
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "discount": 9.99,
        "discountMinor": 1,
        "netPrice": 29.99,
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "boundMonths": 12,
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {
          "propertyName": 9.99
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "assignedTo": {
      "type": "SUBSCRIPTION",
      "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
      "subscriptionDisplay": "+1 (555) 123-4567"
    },
    "customer": {
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "John Doe"
    },
    "activatedAt": "2024-01-15T10:30:00Z"
  },
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "productOffering": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "discount": 9.99,
        "discountMinor": 1,
        "netPrice": 29.99,
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "boundMonths": 12,
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {
          "propertyName": 9.99
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    },
    "scheduledAt": "2024-02-01"
  },
  "addedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T09:00:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "expiredAt": "2024-07-15T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

AddAddonRequest

Request to add an add-on to a subscription.

productOfferingIdstringrequired

The unique identifier of the add-on product offering to add. Use the addon-options endpoint to discover which add-ons are available for the subscription.

scheduledAtstringdate

The date when the add-on should be added. If not provided, the add-on will be added immediately or according to the default schedule.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
AddAddonRequest
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "metadata": {
    "propertyName": "string"
  }
}

CancelSubscriptionRequest

Request to cancel a subscription.

cancelAtone ofrequired

When the subscription should be cancelled.

Show child attributes
nextDaybooleanrequired

Cancel the subscription the next day.

nextMonthbooleanrequired

Cancel the subscription at the beginning of next month.

datestringdaterequired

Cancel the subscription on a specific date.

churnenum<string>

Standardized reason for the cancellation used for reporting and analysis.

If OTHER is provided, please also provide a comment.

values

  • BETTER_DEAL_PRICE
  • NOT_HAPPY_MISSING_FUNCTIONS
  • NOT_HAPPY_COVERAGE_SLA
  • NOT_HAPPY_COMPLEX_ADMIN
  • NOT_HAPPY_SUPPORT_ENGAGEMENT
  • FRAUD
  • FRAUD_ATTEMPT
  • TEST_OR_MARKETING
  • NO_NEED
  • WRONG_ORDER
  • OTHER
commentstring

Optional comment about the cancellation.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CancelSubscriptionRequest
{
  "cancelAt": {
    "nextDay": true
  },
  "churn": "BETTER_DEAL_PRICE",
  "comment": "Switching to a different provider",
  "metadata": {
    "propertyName": "string"
  }
}

SuspendSubscriptionRequest

Request to temporarily suspend a subscription. The customer continues to pay but service is disabled.

scheduledAtstringdate

Suspend the subscription on a specific date.

reasonstring

Optional reason for the suspension.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
SuspendSubscriptionRequest
{
  "scheduledAt": "2024-02-01",
  "reason": "Payment overdue",
  "metadata": {
    "propertyName": "string"
  }
}

PauseSubscriptionRequest

Request to pause a subscription. The customer stops paying and service is disabled.

scheduledAtstringdate

Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
PauseSubscriptionRequest
{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}

RestoreSubscriptionRequest

Request to restore a suspended, paused, or blocked subscription back to active state.

scheduledAtstringdate

Restore the subscription on a specific date.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
RestoreSubscriptionRequest
{
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}

ChangeSubscriptionSimRequest

Request to change the SIM card (ICC/ICCID) for a subscription.

scheduledAtstringdate

Change the SIM card on a specific date.

iccstringrequired

The ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile.

simCardTypeenum<string>required

The type of SIM card being installed.

values

  • PHYSICAL
  • ESIM
metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ChangeSubscriptionSimRequest
{
  "scheduledAt": "2024-02-01",
  "icc": "89012345678901234567",
  "simCardType": "PHYSICAL",
  "metadata": {
    "propertyName": "string"
  }
}

CancelAddonRequest

Request to cancel an add-on from a subscription.

subscriptionAddonIdstringrequired

The identifier of the subscription add-on to cancel. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_telna-package-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

scheduledAtstringdate

The date when the add-on should be canceled. If not provided, the add-on will be canceled immediately or according to the default schedule.

reasonstring

Free-text explanation of why the add-on is being canceled. Stored with the cancellation for audit and reporting; not shown to the subscriber.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CancelAddonRequest
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-03-01",
  "reason": "No longer needed",
  "metadata": {
    "propertyName": "string"
  }
}

ChangeAddonRequest

Request to change an existing add-on to a different product offering.

subscriptionAddonIdstringrequired

The identifier of the subscription add-on to change. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_telna-package-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

productOfferingIdstringrequired

The unique identifier of the new add-on product offering to change to.

scheduledAtstringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text explanation of why the add-on is being changed. Stored with the change for audit and reporting; not shown to the subscriber.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ChangeAddonRequest
{
  "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "productOfferingId": "addon-data-5gb",
  "scheduledAt": "2024-02-01",
  "reason": "Customer upgrade request",
  "metadata": {
    "propertyName": "string"
  }
}

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
enum<string>

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
UsagePackageStatus
"ACTIVE"

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.

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageVoicePackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Unlimited National",
  "callSeconds": 3600,
  "callCount": 15,
  "callRemainingSeconds": 32400,
  "callTotalSeconds": 36000,
  "status": "ACTIVE",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-02-01T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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.

subscriptionAddonIdstring

The subscription add-on that granted this balance. Present only when the balance comes from an add-on.

namestringrequired

Human-readable name of the package, as shown to end users.

balancenumberdoubledeprecated

Deprecated. Use balanceMinor instead.

Remaining prepaid amount available for international long distance calls, in major units of the currency given by currency.

balanceMinorintegerint64

Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.

currencystring

Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.

expiryDatestringdate

The date the remaining balance expires and can no longer be used. Absent when the balance does not expire.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageVoiceIldPackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "ILD Top-up",
  "balance": 15.5,
  "balanceMinor": 1550,
  "currency": "USD",
  "expiryDate": "2025-12-31",
  "metadata": {
    "propertyName": "string"
  }
}

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).

nationalarray of UsageVoicePackage

Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageVoicePackage

Allowance buckets for calls made while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageVoiceIldPackage

International 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
subscriptionAddonIdstring

The subscription add-on that granted this balance. Present only when the balance comes from an add-on.

namestringrequired

Human-readable name of the package, as shown to end users.

balancenumberdoubledeprecated

Deprecated. Use balanceMinor instead.

Remaining prepaid amount available for international long distance calls, in major units of the currency given by currency.

balanceMinorintegerint64

Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.

currencystring

Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.

expiryDatestringdate

The date the remaining balance expires and can no longer be used. Absent when the balance does not expire.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageVoice
{
  "national": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Unlimited National",
      "callSeconds": 3600,
      "callCount": 15,
      "callRemainingSeconds": 32400,
      "callTotalSeconds": 36000,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "roaming": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Unlimited National",
      "callSeconds": 3600,
      "callCount": 15,
      "callRemainingSeconds": 32400,
      "callTotalSeconds": 36000,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "ild": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "ILD Top-up",
      "balance": 15.5,
      "balanceMinor": 1550,
      "currency": "USD",
      "expiryDate": "2025-12-31",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

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.

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageSmsPackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "500 SMS National",
  "smsCount": 25,
  "smsRemaining": 475,
  "smsTotal": 500,
  "status": "ACTIVE",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-02-01T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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).

nationalarray of UsageSmsPackage

Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageSmsPackage

Allowance buckets for messages sent while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageSmsPackage

Allowance buckets for messages sent from the home country to foreign numbers (international long distance).

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageSms
{
  "national": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "500 SMS National",
      "smsCount": 25,
      "smsRemaining": 475,
      "smsTotal": 500,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "roaming": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "500 SMS National",
      "smsCount": 25,
      "smsRemaining": 475,
      "smsTotal": 500,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "ild": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "500 SMS National",
      "smsCount": 25,
      "smsRemaining": 475,
      "smsTotal": 500,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

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.

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageMmsPackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "100 MMS National",
  "mmsCount": 10,
  "mmsRemaining": 90,
  "mmsTotal": 100,
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-02-01T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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).

nationalarray of UsageMmsPackage

Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageMmsPackage

Allowance buckets for multimedia messages sent while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageMmsPackage

Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageMms
{
  "national": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "100 MMS National",
      "mmsCount": 10,
      "mmsRemaining": 90,
      "mmsTotal": 100,
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "roaming": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "100 MMS National",
      "mmsCount": 10,
      "mmsRemaining": 90,
      "mmsTotal": 100,
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "ild": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "100 MMS National",
      "mmsCount": 10,
      "mmsRemaining": 90,
      "mmsTotal": 100,
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

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.

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

rlahBytesUsedintegerint64

Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.

rlahBytesRemainingintegerint64

RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.

rlahBytesTotalintegerint64

The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageDataNationalPackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "10GB National",
  "dataBytesUsed": 3221225472,
  "dataBytesRemaining": 7516192768,
  "dataBytesTotal": 10737418240,
  "rlahBytesUsed": 1073741824,
  "rlahBytesRemaining": 4294967296,
  "rlahBytesTotal": 5368709120,
  "status": "ACTIVE",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-02-01T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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.

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageDataRoamingPackage
{
  "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Asia 5GB Roaming",
  "dataBytesUsed": 1073741824,
  "dataBytesRemaining": 4294967296,
  "dataBytesTotal": 5368709120,
  "status": "ACTIVE",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-02-01T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

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 UsageDataNationalPackage

Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

rlahBytesUsedintegerint64

Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.

rlahBytesRemainingintegerint64

RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.

rlahBytesTotalintegerint64

The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageDataRoamingPackage

Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UsageData
{
  "national": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "10GB National",
      "dataBytesUsed": 3221225472,
      "dataBytesRemaining": 7516192768,
      "dataBytesTotal": 10737418240,
      "rlahBytesUsed": 1073741824,
      "rlahBytesRemaining": 4294967296,
      "rlahBytesTotal": 5368709120,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ],
  "roaming": [
    {
      "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Asia 5GB Roaming",
      "dataBytesUsed": 1073741824,
      "dataBytesRemaining": 4294967296,
      "dataBytesTotal": 5368709120,
      "status": "ACTIVE",
      "validFrom": "2025-01-01T00:00:00Z",
      "validTo": "2025-02-01T00:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

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.

voiceobject

Voice call usage across all scopes and packages.

Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers).

Show child attributes
nationalarray of UsageVoicePackage

Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageVoicePackage

Allowance buckets for calls made while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageVoiceIldPackage

International 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
subscriptionAddonIdstring

The subscription add-on that granted this balance. Present only when the balance comes from an add-on.

namestringrequired

Human-readable name of the package, as shown to end users.

balancenumberdoubledeprecated

Deprecated. Use balanceMinor instead.

Remaining prepaid amount available for international long distance calls, in major units of the currency given by currency.

balanceMinorintegerint64

Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.

currencystring

Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.

expiryDatestringdate

The date the remaining balance expires and can no longer be used. Absent when the balance does not expire.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
smsobject

SMS usage across all scopes and packages.

SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes
nationalarray of UsageSmsPackage

Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageSmsPackage

Allowance buckets for messages sent while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageSmsPackage

Allowance buckets for messages sent from the home country to foreign numbers (international long distance).

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
mmsobject

MMS usage across all scopes and packages.

MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes
nationalarray of UsageMmsPackage

Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageMmsPackage

Allowance buckets for multimedia messages sent while roaming abroad.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ildarray of UsageMmsPackage

Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
dataobject

Data usage across all scopes and packages.

Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad).

Show child attributes
nationalarray of UsageDataNationalPackage

Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

rlahBytesUsedintegerint64

Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.

rlahBytesRemainingintegerint64

RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.

rlahBytesTotalintegerint64

The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
roamingarray of UsageDataRoamingPackage

Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.

Show child attributes
subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

  • ACTIVE: The package is in its validity window and usage draws from it
  • NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
  • EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

  • ACTIVE
  • NOT_ACTIVE
  • EXPIRED
validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
updatedAtstringdate-timerequired

When the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet.

Usage
{
  "voice": {
    "national": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Unlimited National",
        "callSeconds": 3600,
        "callCount": 15,
        "callRemainingSeconds": 32400,
        "callTotalSeconds": 36000,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "roaming": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Unlimited National",
        "callSeconds": 3600,
        "callCount": 15,
        "callRemainingSeconds": 32400,
        "callTotalSeconds": 36000,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "ild": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "ILD Top-up",
        "balance": 15.5,
        "balanceMinor": 1550,
        "currency": "USD",
        "expiryDate": "2025-12-31",
        "metadata": {
          "propertyName": "string"
        }
      }
    ]
  },
  "sms": {
    "national": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "500 SMS National",
        "smsCount": 25,
        "smsRemaining": 475,
        "smsTotal": 500,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "roaming": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "500 SMS National",
        "smsCount": 25,
        "smsRemaining": 475,
        "smsTotal": 500,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "ild": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "500 SMS National",
        "smsCount": 25,
        "smsRemaining": 475,
        "smsTotal": 500,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ]
  },
  "mms": {
    "national": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "100 MMS National",
        "mmsCount": 10,
        "mmsRemaining": 90,
        "mmsTotal": 100,
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "roaming": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "100 MMS National",
        "mmsCount": 10,
        "mmsRemaining": 90,
        "mmsTotal": 100,
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "ild": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "100 MMS National",
        "mmsCount": 10,
        "mmsRemaining": 90,
        "mmsTotal": 100,
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ]
  },
  "data": {
    "national": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "10GB National",
        "dataBytesUsed": 3221225472,
        "dataBytesRemaining": 7516192768,
        "dataBytesTotal": 10737418240,
        "rlahBytesUsed": 1073741824,
        "rlahBytesRemaining": 4294967296,
        "rlahBytesTotal": 5368709120,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ],
    "roaming": [
      {
        "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Asia 5GB Roaming",
        "dataBytesUsed": 1073741824,
        "dataBytesRemaining": 4294967296,
        "dataBytesTotal": 5368709120,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        }
      }
    ]
  },
  "updatedAt": "2024-01-15T10:30:00Z"
}

EsimQrCode

eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL.

subscriptionIdstringrequired

The unique identifier of the subscription this QR code belongs to.

qrCodeDatastringrequired

The QR code data string that contains the eSIM profile download information (LPA format).

qrCodeUrlstringuri

Hosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead.

expiresAtstringdate-time

When 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 keys

A set of key-value pairs that can be attached to an object 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
EsimQrCode
{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "qrCodeData": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012",
  "qrCodeUrl": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "expiresAt": "2024-12-31T23:59:59Z",
  "metadata": {
    "propertyName": "string"
  }
}

SubscriberListItem

Simplified representation of a subscriber (the end user of a subscription) optimized for list operations. Use the detailed Subscriber schema for individual subscriber views.

subscriberIdstringrequired

The unique identifier of the subscriber.

namestringrequired

The full name of the subscriber.

emailstringemail

Optional email address of the subscriber.

addressobject

The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

customerIdstring

The unique identifier of the customer the subscriber belongs to.

subscriptionIdsarray of string

List of subscriptions ids associated with the subscriber.

Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

SubscriberListItem
{
  "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "subscriptionIds": [
    "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
  ],
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

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.

subscriberIdstringrequired

The unique identifier of the subscriber.

namestringrequired

The full name of the subscriber.

emailstringemail

Optional email address of the subscriber.

contactNumberstringphone

A phone number for reaching the subscriber, separate from the number their subscription provides.

addressobject

The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

customerobjectrequired

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

subscriptionsarray of Subscription

List 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
subscriptionIdstringrequired

The unique identifier for the subscription.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
typestringrequired

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.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringphonerequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerobjectrequired

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

namestringrequired

The subscriber's full name.

emailstringemail

The subscriber's email address, if one has been provided.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

imeistring

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

iccidstring

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

pendingMsisdnobject

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes
msisdnstringphonerequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

The date when the pending number change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes
statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
scheduledAtstringdate

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

Show child attributes
msisdnstringrequired

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

statusenum<string>required

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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
directionenum<string>required

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

  • INBOUND
  • OUTBOUND
scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
Subscriber
{
  "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "contactNumber": "+15551234567",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "subscriptions": [
    {
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "referenceId": "crm-subscription-12345",
      "status": "PENDING",
      "type": "CELL",
      "display": "(555) 123-4567",
      "msisdn": "+15551234567",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "productOffering": {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Mobile Unlimited",
        "price": {
          "discount": 9.99,
          "discountMinor": 1,
          "netPrice": 29.99,
          "netPriceMinor": 2999,
          "currency": "USD",
          "priceType": "ONE_TIME",
          "boundMonths": 12,
          "bindingContract": {
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            }
          },
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            }
          },
          "billingCycle": {
            "period": "MONTHLY",
            "interval": 1
          },
          "currencyOptions": {
            "propertyName": 9.99
          },
          "currencyOptionsMinor": {
            "propertyName": 1
          }
        },
        "group": {
          "productOfferingGroupId": "mobile-plans",
          "name": "Mobile Plans",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "internalDescription": "Core mobile offerings targeting consumer and business segments"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
      },
      "subscriber": {
        "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T14:45:00Z"
      },
      "extensions": {
        "propertyName": "string"
      },
      "sim": {
        "esim": true,
        "imei": "356938035643809",
        "iccid": "8901240197155182976"
      },
      "pendingMsisdn": {
        "msisdn": "+15559876543",
        "scheduledAt": "2024-02-01"
      },
      "pendingStatus": {
        "status": "PENDING",
        "scheduledAt": "2024-02-01"
      },
      "pendingProductOffering": {
        "scheduledAt": "2024-02-01",
        "product": {
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "name": "Mobile Unlimited",
          "price": {
            "discount": 9.99,
            "discountMinor": 1,
            "netPrice": 29.99,
            "netPriceMinor": 2999,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "boundMonths": 12,
            "bindingContract": {
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                }
              }
            },
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                }
              }
            },
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "currencyOptions": {
              "propertyName": 9.99
            },
            "currencyOptionsMinor": {
              "propertyName": 1
            }
          },
          "group": {
            "productOfferingGroupId": "mobile-plans",
            "name": "Mobile Plans",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "internalDescription": "Core mobile offerings targeting consumer and business segments"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
        }
      },
      "porting": {
        "msisdn": "+15551234567",
        "status": "PENDING",
        "direction": "INBOUND",
        "scheduledAt": "2024-02-01"
      },
      "activatedAt": "2024-01-15T10:30:00Z",
      "cancelledAt": "2024-06-30T00:00:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

UpdateSubscriberRequest

Request to update a subscriber's information.

namestring

The full name of the subscriber.

emailstringemail

The email address of the subscriber.

contactNumberstringphone

A phone number for reaching the subscriber, separate from the number their subscription provides.

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. Changing it schedules an update with the network operator, so the new address becomes the one emergency services receive.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UpdateSubscriberRequest
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "contactNumber": "+15551234567",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "metadata": {
    "propertyName": "string"
  }
}

License

A license represents a permission to use a software product with embedded customer and product offering details.

licenseIdstringrequired

The unique identifier for the license.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestringrequired

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.

customerobjectrequired

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
discountnumberdecimaldeprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

discountMinorintegerint64deprecated

Deprecated. The API no longer sends this field. To find the discounts that an offering has, read standardDiscount, bindingContract.discount and customUpfrontPayment.discount. To find what a customer pays, price an order.

This field put all the discounts that applied into one number. An offering price no longer applies discounts, so the API never sends this field.

netPricenumberdecimaldeprecated

Deprecated. Use netPriceMinor instead.

The configured price of the offering, in major currency units.

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

priceTypeenum<string>required

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_TIME
  • RECURRING
boundMonthsintegerdeprecated

Deprecated. Use bindingContract.duration instead.

Length of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.

bindingContractobject

A 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
standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not 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
customUpfrontPaymentobject

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.

Show child attributes
billingCycleobject

How often a recurring price is charged.

Show child attributes
currencyOptionsobject with string keysdeprecated

Deprecated. Use currencyOptionsMinor instead.

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in major currency units.

Show child attributes
currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

A product category is a sub-type for grouping offerings of the same type.

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
internalDescriptionstring

Internal description of the product group for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

assignedToone of

Assignment details for a license, indicating what entity the license is assigned to. This embedded version includes additional display information for each assignment type.

Show child attributes
typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier for the subscription

subscriptionDisplaystring

Display name for the subscription (typically the phone number)

detailsobject

Additional license details specific to certain license types.

Show child attributes
propertyNameany

Any additional properties, passed through as given.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
statusenum<string>required

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

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
scheduledAtstringdaterequired

The date when the pending status change is scheduled to occur.

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

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.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

activatedAtstringdaterequired

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled (if applicable).

pausedAtstringdate

The date when the license was paused (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
License
{
  "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
  "status": "PENDING",
  "type": "PBX_USER_LEVEL",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "productOffering": {
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Mobile Unlimited",
    "price": {
      "discount": 9.99,
      "discountMinor": 1,
      "netPrice": 29.99,
      "netPriceMinor": 2999,
      "currency": "USD",
      "priceType": "ONE_TIME",
      "boundMonths": 12,
      "bindingContract": {
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        }
      },
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      },
      "currencyOptions": {
        "propertyName": 9.99
      },
      "currencyOptionsMinor": {
        "propertyName": 1
      }
    },
    "group": {
      "productOfferingGroupId": "mobile-plans",
      "name": "Mobile Plans",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "internalDescription": "Core mobile offerings targeting consumer and business segments"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
  },
  "assignedTo": {
    "type": "SUBSCRIPTION",
    "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
    "subscriptionDisplay": "+1 (555) 123-4567"
  },
  "details": {},
  "pendingStatus": {
    "status": "PENDING",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "scheduledAt": "2024-02-01",
    "product": {
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Mobile Unlimited",
      "price": {
        "discount": 9.99,
        "discountMinor": 1,
        "netPrice": 29.99,
        "netPriceMinor": 2999,
        "currency": "USD",
        "priceType": "ONE_TIME",
        "boundMonths": 12,
        "bindingContract": {
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          }
        },
        "billingCycle": {
          "period": "MONTHLY",
          "interval": 1
        },
        "currencyOptions": {
          "propertyName": 9.99
        },
        "currencyOptionsMinor": {
          "propertyName": 1
        }
      },
      "group": {
        "productOfferingGroupId": "mobile-plans",
        "name": "Mobile Plans",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "internalDescription": "Core mobile offerings targeting consumer and business segments"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png"
    }
  },
  "activatedAt": "2024-01-15",
  "cancelledAt": "2024-06-30",
  "pausedAt": "2024-03-01",
  "metadata": {
    "propertyName": "string"
  }
}

AssignedTo

Assignment reference for a license, indicating what entity the license is assigned to. This is a simplified version for list operations - use EmbeddedAssignedTo for detailed views.

typeenum<string>required

The type of entity the license is assigned to.

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier of the subscription the license is assigned to.

AssignedTo
{
  "type": "SUBSCRIPTION",
  "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786"
}

CreateLicenseRequest

Create a new license.

Note: this endpoint is disabled when Seamless OS manages billing, licenses can then be created by orders.

productOfferingIdstringrequired

The unique identifier for the product offering to subscribe to.

This controls what type of license is being created.

customerIdstringuuidrequired

The unique identifier for the existing customer who will own this license.

licenseTypestringrequired

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.

assignedToone ofrequired

Assignment reference for a license, indicating what entity the license is assigned to. This is a simplified version for list operations - use EmbeddedAssignedTo for detailed views.

Show child attributes
typeenum<string>required

The type of entity the license is assigned to.

values

  • SUBSCRIPTION
subscriptionIdstringrequired

The unique identifier of the subscription the license is assigned to.

scheduleActivationAtstringdate

Date when the license should be activated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreateLicenseRequest
{
  "productOfferingId": "a7b8c9d0-e1f2-3456-7890-bcdef0123456",
  "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567",
  "licenseType": "PBX_USER_LEVEL",
  "assignedTo": {
    "type": "SUBSCRIPTION",
    "subscriptionId": "c9d0e1f2-a3b4-5678-9012-def012345678"
  },
  "scheduleActivationAt": "2024-01-20"
}

ChangeLicenseProductOfferingRequest

Request to change the product offering of a license.

productOfferingIdstringrequired

The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the license can be changed to.

scheduledAtstringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
ChangeLicenseProductOfferingRequest
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  }
}

CancelLicenseRequest

Request to cancel a license.

scheduledAtstringdate

The date when the license should be cancelled. If not provided, the license will be cancelled immediately or according to the default schedule.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CancelLicenseRequest
{
  "scheduledAt": "2024-03-01",
  "metadata": {
    "propertyName": "string"
  }
}

ProductCatalogListItem

A product catalog defines a curated set of product offerings for a specific context such as customer segment, region, or sales channel.

productCatalogIdstringrequired

Unique identifier for the product catalog.

namestringrequired

Name of the product catalog.

descriptionstring

Description of the product catalog.

extendsDefaultbooleanrequired

Whether this catalog extends the default product catalog. When true, the catalog inherits all offerings from the default catalog in addition to its own.

isDefaultboolean

Whether this is the default catalog for its customer type. A customer with no catalog of their own is served the default one.

customerTypeenum<string>

The kind of customer this catalog serves. Absent on catalogs that have not been assigned a customer type.

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
ProductCatalogListItem
{
  "productCatalogId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "US Consumer Catalog",
  "description": "Product catalog for US consumer customers",
  "extendsDefault": true,
  "isDefault": true,
  "customerType": "CONSUMER"
}

EmbeddedDiscount

Essential discount information without sensitive details.

discountIdstringrequired

The unique identifier for the discount.

descriptionstringrequired

A description of what the discount provides.

tagstring

A short label or category for the discount.

createdAtstringdate-time

When the discount was created.

updatedAtstringdate-time

When the discount was last updated.

EmbeddedDiscount
{
  "discountId": "80df6fdf-c450-406e-948b-f77d4ac1cdb8",
  "description": "25% Off Summer Promo",
  "tag": "SUMMER25",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Promotion

A promotion that applies a discount when the promotional code is used.

promotionIdstringrequired

The unique identifier for the promotion.

promoCodestringrequired

The promotional code that customers can use to activate this promotion.

discountPeriodMonthsintegerrequired

The number of months the discount will be applied.

validFromstringdate

When the promotion becomes valid and can be used.

If not provided, the promotion is valid immediately.

validTostringdate

When the promotion expires and can no longer be used.

If not provided, the promotion does not expire.

discountIdstringrequired

The unique identifier for the discount that this promotion applies to.

discountobjectrequired

Essential discount information without sensitive details.

Show child attributes
discountIdstringrequired

The unique identifier for the discount.

descriptionstringrequired

A description of what the discount provides.

tagstring

A short label or category for the discount.

createdAtstringdate-time

When the discount was created.

updatedAtstringdate-time

When the discount was last updated.

Promotion
{
  "promotionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "promoCode": "SUMMER25",
  "discountPeriodMonths": 12,
  "validFrom": "2024-02-01",
  "validTo": "2024-02-01",
  "discountId": "80df6fdf-c450-406e-948b-f77d4ac1cdb8",
  "discount": {
    "discountId": "80df6fdf-c450-406e-948b-f77d4ac1cdb8",
    "description": "25% Off Summer Promo",
    "tag": "SUMMER25",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  }
}

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
enum<string>

values

  • PENDING
  • PENDING_PAYMENT
  • SUBMITTED
  • PENDING_APPROVAL
  • PROCESSING
  • COMPLETED
  • CANCELLED
  • EXPIRED
  • FAILED
OrderState
"PENDING"

OrderListItem

Optimized order representation for list operations.

orderIdstringrequired

The unique identifier for the order.

stateenum<string>required

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

  • PENDING
  • PENDING_PAYMENT
  • SUBMITTED
  • PENDING_APPROVAL
  • PROCESSING
  • COMPLETED
  • CANCELLED
  • EXPIRED
  • FAILED
customerobject

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

pricingobject

Summary pricing information for the order.

Show child attributes
totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Final order total including all taxes and fees, in major currency units.

totalMinorintegerint64required

Final order total including all taxes and fees, in minor currency units.

currencystringrequired

ISO 4217 currency code.

validationStatusenum<string>

Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid.

values

  • VALID
  • INVALID
  • PENDING_VALIDATION
createdAtstringdate-timerequired

When the order was created.

updatedAtstringdate-timerequired

When the order was last updated.

expiresAtstringdate-time

When the order will expire if not submitted.

OrderListItem
{
  "orderId": "ce0539b4-ec57-4709-b72e-47892586d05a",
  "state": "PENDING",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "pricing": {
    "total": 137.39,
    "totalMinor": 13739,
    "currency": "USD"
  },
  "validationStatus": "VALID",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-22T10:30:00Z"
}

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.

enum<string>

values

  • CONSUMER
  • BUSINESS
OrderCustomerType
"CONSUMER"

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.

namestringrequired

The user's full name.

emailstringemailrequired

The email the user logs in with and receives order confirmations on.

identitystring

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.

msisdnstringphone

The user's phone number.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
OrderUserReference_NewUser
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "identity": "12-3456789",
  "msisdn": "+15551234567",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "metadata": {
    "propertyName": "string"
  }
}

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.

userIdstringrequired

The user's internal ID.

authenticatedUserbooleanrequired

Always true.

namestringrequired

The user's full name.

emailstringemailrequired

The email the user logs in with and receives order confirmations on.

identitystring

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.

msisdnstringphone

The user's phone number.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
OrderUserReference
{
  "userId": "d47ac10b-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.

referenceIdstringmax length 255

Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.

namestringrequired

Name for the new customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
identitystring

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.

preferredLocalestring

Preferred locale for the customer.

contactobject

Contact information for the new customer.

Show child attributes
emailstringemail

Primary contact email for the new customer.

msisdnstringphone

Primary contact phone number for the new customer.

billingobject

Billing configuration and payment preferences for the new customer.

Show child attributes
methodenum<string>required

How invoices should be delivered to the customer.

How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.

values

  • E_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Used for invoicing and tax calculation.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

autoPaybooleandefault false

Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
OrderCustomerReference_NewCustomer
{
  "referenceId": "crm-customer-12345",
  "name": "Acme Corporation",
  "customerType": "CONSUMER",
  "identity": "12-3456789",
  "preferredLocale": "en-US",
  "contact": {
    "email": "billing@acme.com",
    "msisdn": "+15551234567"
  },
  "billing": {
    "method": "E_INVOICE",
    "email": "billing@acme.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "currency": "USD",
    "autoPay": true
  },
  "metadata": {
    "propertyName": "string"
  }
}

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.

customerIdstringrequired

The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.

authenticatedCustomerbooleanrequired

Always true.

referenceIdstringmax length 255

Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.

namestringrequired

Name for the new customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
identitystring

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.

preferredLocalestring

Preferred locale for the customer.

contactobject

Contact information for the new customer.

Show child attributes
emailstringemail

Primary contact email for the new customer.

msisdnstringphone

Primary contact phone number for the new customer.

billingobject

Billing configuration and payment preferences for the new customer.

Show child attributes
methodenum<string>required

How invoices should be delivered to the customer.

How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.

values

  • E_INVOICE
  • EMAIL_INVOICE
  • PAPER_INVOICE
emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Used for invoicing and tax calculation.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

autoPaybooleandefault false

Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
OrderCustomerReference
{
  "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
}

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.

namestring

Billing contact name.

emailstringemail

Billing contact email.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

OrderBilling
{
  "name": "John Doe",
  "email": "billing@example.com",
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

OrderLineItemStatus

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

enum<string>

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
OrderLineItemStatus
"PENDING"

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.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
detailsone ofrequired

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.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
*string
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
namestring

Name of the subscriber.

emailstringemail

Contact email of the subscriber.

msisdnstringphone

Contact phone number of the subscriber. May be the same as the subscription's msisdn.

addressobject

The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions.

In the US, this is the E911 address.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
esimbooleanrequired

Whether this subscription should use eSIM technology.

imeistring

International Mobile Equipment Identity for eSIM activation.

Some networks require this to activate the eSIM.

iccidstring

Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.

This feature only applies to certain networks.

scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
SubscriptionLineItem
{
  "type": "SUBSCRIPTION",
  "lineItemId": "line-item-1",
  "productOfferingId": "mobile-plan-basic",
  "msisdn": "+15551234567",
  "leaseToken": "lease_8f3b1c2d4e5f6789",
  "tempNumber": true,
  "portingRequested": true,
  "porting": {
    "details": {
      "accountNumber": "987654321",
      "passcode": "123456",
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "street1": "500 S Main St",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      }
    }
  },
  "extensions": {
    "propertyName": "string"
  },
  "display": "John Doe - Work phone",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8931440400000000000"
  },
  "scheduleActivationAt": "2024-02-01",
  "activateOnDemand": true,
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

AddonLineItem

Line item for adding an add-on to a subscription.

typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
AddonLineItem
{
  "type": "ADDON",
  "lineItemId": "line-item-3",
  "productOfferingId": "addon-data-5gb",
  "subscriptionId": "subscription-456",
  "parentLineItemId": "line-item-1",
  "scheduledAt": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

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.

typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
ExternalProductLineItem
{
  "type": "EXTERNAL_PRODUCT",
  "lineItemId": "line-item-5",
  "productOfferingId": "external-device-iphone15",
  "quantity": 2,
  "parentLineItemId": "line-item-1",
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

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.

typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
amountMinorintegerint64required

The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the price is expressed in. Must match the order currency.

quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
ExternalLineItem
{
  "type": "EXTERNAL",
  "lineItemId": "line-item-6",
  "name": "Custom Installation Service",
  "description": "Professional on-site installation and setup",
  "price": {
    "amountMinor": 9999,
    "currency": "USD"
  },
  "quantity": 1,
  "taxationId": "TAX123456",
  "fulfillmentWebhook": "https://partner.com/webhooks/fulfillment",
  "parentLineItemId": "line-item-1",
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

SubscriptionChangeLineItem

Line item for changing a subscription's product offering.

typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
SubscriptionChangeLineItem
{
  "type": "SUBSCRIPTION_CHANGE",
  "lineItemId": "line-item-7",
  "subscriptionId": "subscription-456",
  "productOfferingId": "mobile-plan-premium",
  "scheduleDate": "2024-02-01",
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

AddonChangeLineItem

Line item for changing an add-on's product offering.

typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
AddonChangeLineItem
{
  "type": "ADDON_CHANGE",
  "lineItemId": "line-item-9",
  "subscriptionId": "subscription-456",
  "addonId": "addon-123",
  "productOfferingId": "addon-data-5gb",
  "scheduleDate": "2024-02-01",
  "reason": "Customer upgrade request",
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

OrderLineItem

A line item in an order representing a billable action or service.

Selected by type.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
detailsone ofrequired

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.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
*string
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
namestring

Name of the subscriber.

emailstringemail

Contact email of the subscriber.

msisdnstringphone

Contact phone number of the subscriber. May be the same as the subscription's msisdn.

addressobject

The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions.

In the US, this is the E911 address.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
esimbooleanrequired

Whether this subscription should use eSIM technology.

imeistring

International Mobile Equipment Identity for eSIM activation.

Some networks require this to activate the eSIM.

iccidstring

Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.

This feature only applies to certain networks.

scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
amountMinorintegerint64required

The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the price is expressed in. Must match the order currency.

quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
OrderLineItem
{
  "type": "SUBSCRIPTION",
  "lineItemId": "line-item-1",
  "productOfferingId": "mobile-plan-basic",
  "msisdn": "+15551234567",
  "leaseToken": "lease_8f3b1c2d4e5f6789",
  "tempNumber": true,
  "portingRequested": true,
  "porting": {
    "details": {
      "accountNumber": "987654321",
      "passcode": "123456",
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "street1": "500 S Main St",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      }
    }
  },
  "extensions": {
    "propertyName": "string"
  },
  "display": "John Doe - Work phone",
  "subscriber": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "sim": {
    "esim": true,
    "imei": "356938035643809",
    "iccid": "8931440400000000000"
  },
  "scheduleActivationAt": "2024-02-01",
  "activateOnDemand": true,
  "metadata": {
    "propertyName": "string"
  },
  "status": "PENDING"
}

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
Consents
{
  "termsOfService": "true",
  "marketing": "true"
}

CreateOrderRequest

Request to create a new order. Orders can be created with minimal information and progressively configured. User and customer information can be added later, including through mid-flow authentication.

customerTypeenum<string>required

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

  • CONSUMER
  • BUSINESS
userone of

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.

Show child attributes
userIdstringrequired

The user's internal ID.

authenticatedUserbooleanrequired

Always true.

namestringrequired

The user's full name.

emailstringemailrequired

The email the user logs in with and receives order confirmations on.

identitystring

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.

msisdnstringphone

The user's phone number.

addressobject

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 keys

A set of key-value pairs that can be attached to an object 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
customerone of

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.

Show child attributes
customerIdstringrequired

The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.

authenticatedCustomerbooleanrequired

Always true.

referenceIdstringmax length 255

Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.

namestringrequired

Name for the new customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
identitystring

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.

preferredLocalestring

Preferred locale for the customer.

contactobject

Contact information for the new customer.

Show child attributes
billingobject

Billing configuration and payment preferences for the new customer.

Show child attributes
metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
billingobject

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.

Show child attributes
namestring

Billing contact name.

emailstringemail

Billing contact email.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

shippingobject

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes
namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

lineItemsarray of OrderLineItem

Initial line items for the order (can be empty).

Show child attributes

Selected by type.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
consentsobject with string keys

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.

Show child attributes
*string
promoCodestring

Promo code to apply to the order. Rejected with promo_code_not_redeemable when no promotion has that code, or when it is outside its validity period.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreateOrderRequest
{
  "customerType": "CONSUMER",
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "instructions": "Leave at front door"
  },
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "msisdn": "+15551234567",
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "tempNumber": true,
      "portingRequested": true,
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "passcode": "123456",
          "firstName": "John",
          "lastName": "Doe",
          "address": {
            "street1": "500 S Main St",
            "street2": "Apt 1",
            "city": "Natick",
            "zip": "01701",
            "country": "US",
            "state": "CA",
            "region": "Ontario",
            "attention": "John Doe"
          }
        }
      },
      "extensions": {
        "propertyName": "string"
      },
      "display": "John Doe - Work phone",
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      },
      "sim": {
        "esim": true,
        "imei": "356938035643809",
        "iccid": "8931440400000000000"
      },
      "scheduleActivationAt": "2024-02-01",
      "activateOnDemand": true,
      "metadata": {
        "propertyName": "string"
      },
      "status": "PENDING"
    }
  ],
  "consents": {
    "termsOfService": "true",
    "marketing": "true"
  },
  "promoCode": "SUMMER2023",
  "metadata": {
    "propertyName": "string"
  }
}

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.

userIdstring

The user's identifier, once the user exists.

namestring

The user's full name.

emailstringemail

The email the user logs in with.

newUserbooleanrequired

Whether this user is created as part of fulfilling the order.

OrderUserResult
{
  "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "newUser": true
}

OrderCustomerResult

The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.

customerIdstring

The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
namestringrequired

Customer name.

newCustomerbooleanrequired

Indicates if the customer was/will be created as part of order fulfillment.

OrderCustomerResult
{
  "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerType": "CONSUMER",
  "name": "John Doe",
  "newCustomer": true
}

OrderPricingSummary

The price of an order. In regions with complex tax rules (e.g., the US), you need to call the price calculation endpoint to get accurate tax amounts before submitting the order. In other regions, tax is dependent on customer type but typically included.

All amounts are in minor units of the currency (e.g., 13739 = $137.39 when the currency is USD).

subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Subtotal after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64

Subtotal after discounts and before taxes and fees, in minor currency units. Add the totalDiscountsMinor of each line item to it to get the amount before discounts.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total amount due for the order, in major currency units.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

currencystringrequired

The ISO 4217 currency code for all pricing amounts (e.g., "USD").

recurringCostsobject

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

A discount that ends with the periods paid for up front is not applied here.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Recurring subtotal after discounts and before taxes, in major currency units.

subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total estimated recurring amount, in major currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on recurring charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on recurring charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

initialInvoiceobject

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

First invoice subtotal (e.g., prorated amount, setup fees), in major currency units.

subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total first invoice amount, in major currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on initial invoice charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on initial invoice charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

periodobject

Period covered by the initial invoice.

Show child attributes
startstringdate

Start date of the initial billing period.

endstringdate

End date of the initial billing period.

calculatedAtstringdate-timerequired

When the pricing was last calculated.

OrderPricingSummary
{
  "subtotal": 125.99,
  "subtotalMinor": 12599,
  "taxAmount": 10.08,
  "taxAmountMinor": 1008,
  "total": 137.39,
  "totalMinor": 13739,
  "taxIncluded": true,
  "currency": "USD",
  "recurringCosts": {
    "subtotal": 29.99,
    "subtotalMinor": 2999,
    "total": 32.39,
    "totalMinor": 3239,
    "taxAmount": 2.4,
    "taxAmountMinor": 240,
    "taxIncluded": true,
    "billingCycle": {
      "period": "MONTHLY",
      "interval": 1
    }
  },
  "initialInvoice": {
    "subtotal": 14.5,
    "subtotalMinor": 1450,
    "total": 15.66,
    "totalMinor": 1566,
    "taxAmount": 1.16,
    "taxAmountMinor": 116,
    "taxIncluded": true,
    "period": {
      "start": "2024-01-15",
      "end": "2024-01-31"
    }
  },
  "calculatedAt": "2024-01-15T10:30:00Z"
}

TaxBreakdownItem

A single tax or fee contributing to the total tax on a charge, such as state sales tax or a regulatory fee.

descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

The amount charged for this tax component, in major units of the currency of the transaction.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

TaxBreakdownItem
{
  "description": "Sales Tax",
  "amount": 2.4,
  "amountMinor": 240,
  "rate": 8.25
}

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).

lineItemIdstringrequired

The line item in the order that this pricing applies to.

subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Amount for this line item after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64required

Amount for this line item after discounts and before taxes and fees, in minor currency units. Add totalDiscountsMinor to it to get the amount before discounts.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Amount due for this line item after taxes, fees, and discounts, in major currency units.

totalMinorintegerint64required

Amount due for this line item after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

The individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.

Show child attributes
descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

The amount charged for this tax component, in major units of the currency of the transaction.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Total taxes for this line item, in major currency units.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of object

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount.

Show child attributes
namestringrequired

Discount name or description.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

Discount amount (positive value), in major currency units.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsnumberdecimaldeprecated

Deprecated. Use totalDiscountsMinor instead.

Total discounts for this line item, in major currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountnumberdecimaldeprecated

Deprecated. Use recurringAmountMinor instead.

Recurring cost for this line item per billing cycle, in major currency units.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

initialInvoiceAmountnumberdecimaldeprecated

Deprecated. Use initialInvoiceAmountMinor instead.

Amount for this line item on the first invoice when different from recurring, in major currency units.

initialInvoiceAmountMinorintegerint64

Amount for this line item on the first invoice when different from recurring, in minor currency units.

OrderLineItemPricing
{
  "lineItemId": "line-item-1",
  "subtotal": 29.99,
  "subtotalMinor": 2999,
  "total": 27.47,
  "totalMinor": 2747,
  "taxBreakdown": [
    {
      "description": "Sales Tax",
      "amount": 2.4,
      "amountMinor": 240,
      "rate": 8.25
    }
  ],
  "taxAmount": 2.47,
  "taxAmountMinor": 247,
  "taxIncluded": true,
  "discounts": [
    {
      "name": "First month free",
      "amount": 29.99,
      "amountMinor": 2999
    }
  ],
  "totalDiscounts": 29.99,
  "totalDiscountsMinor": 2999,
  "description": "Premium Plan",
  "recurringAmount": 29.99,
  "recurringAmountMinor": 2999,
  "initialInvoiceAmount": 14.5,
  "initialInvoiceAmountMinor": 1450
}

OrderPricing

Detailed pricing information for an order including taxes and discounts.

subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Subtotal after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64

Subtotal after discounts and before taxes and fees, in minor currency units. Add the totalDiscountsMinor of each line item to it to get the amount before discounts.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total amount due for the order, in major currency units.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

currencystringrequired

The ISO 4217 currency code for all pricing amounts (e.g., "USD").

recurringCostsobject

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

A discount that ends with the periods paid for up front is not applied here.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Recurring subtotal after discounts and before taxes, in major currency units.

subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total estimated recurring amount, in major currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on recurring charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on recurring charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

billingCycleobject

How often a recurring price is charged.

Show child attributes
periodenum<string>required

The unit of time between charges. Currently only monthly billing is supported.

values

  • MONTHLY
intervalintegerrequired

The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months.

initialInvoiceobject

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

First invoice subtotal (e.g., prorated amount, setup fees), in major currency units.

subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total first invoice amount, in major currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on initial invoice charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on initial invoice charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

periodobject

Period covered by the initial invoice.

Show child attributes
startstringdate

Start date of the initial billing period.

endstringdate

End date of the initial billing period.

calculatedAtstringdate-timerequired

When the pricing was last calculated.

lineItemsarray of OrderLineItemPricing

Pricing breakdown per line item.

Show child attributes
lineItemIdstringrequired

The line item in the order that this pricing applies to.

subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Amount for this line item after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64required

Amount for this line item after discounts and before taxes and fees, in minor currency units. Add totalDiscountsMinor to it to get the amount before discounts.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Amount due for this line item after taxes, fees, and discounts, in major currency units.

totalMinorintegerint64required

Amount due for this line item after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

The individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.

Show child attributes
descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

The amount charged for this tax component, in major units of the currency of the transaction.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Total taxes for this line item, in major currency units.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of object

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount.

Show child attributes
namestringrequired

Discount name or description.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

Discount amount (positive value), in major currency units.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsnumberdecimaldeprecated

Deprecated. Use totalDiscountsMinor instead.

Total discounts for this line item, in major currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountnumberdecimaldeprecated

Deprecated. Use recurringAmountMinor instead.

Recurring cost for this line item per billing cycle, in major currency units.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

initialInvoiceAmountnumberdecimaldeprecated

Deprecated. Use initialInvoiceAmountMinor instead.

Amount for this line item on the first invoice when different from recurring, in major currency units.

initialInvoiceAmountMinorintegerint64

Amount for this line item on the first invoice when different from recurring, in minor currency units.

OrderPricing
{
  "subtotal": 125.99,
  "subtotalMinor": 12599,
  "taxAmount": 10.08,
  "taxAmountMinor": 1008,
  "total": 137.39,
  "totalMinor": 13739,
  "taxIncluded": true,
  "currency": "USD",
  "recurringCosts": {
    "subtotal": 29.99,
    "subtotalMinor": 2999,
    "total": 32.39,
    "totalMinor": 3239,
    "taxAmount": 2.4,
    "taxAmountMinor": 240,
    "taxIncluded": true,
    "billingCycle": {
      "period": "MONTHLY",
      "interval": 1
    }
  },
  "initialInvoice": {
    "subtotal": 14.5,
    "subtotalMinor": 1450,
    "total": 15.66,
    "totalMinor": 1566,
    "taxAmount": 1.16,
    "taxAmountMinor": 116,
    "taxIncluded": true,
    "period": {
      "start": "2024-01-15",
      "end": "2024-01-31"
    }
  },
  "calculatedAt": "2024-01-15T10:30:00Z",
  "lineItems": [
    {
      "lineItemId": "line-item-1",
      "subtotal": 29.99,
      "subtotalMinor": 2999,
      "total": 27.47,
      "totalMinor": 2747,
      "taxBreakdown": [
        {
          "description": "Sales Tax",
          "amount": 2.4,
          "amountMinor": 240,
          "rate": 8.25
        }
      ],
      "taxAmount": 2.47,
      "taxAmountMinor": 247,
      "taxIncluded": true,
      "discounts": [
        {
          "name": "First month free",
          "amount": 29.99,
          "amountMinor": 2999
        }
      ],
      "totalDiscounts": 29.99,
      "totalDiscountsMinor": 2999,
      "description": "Premium Plan",
      "recurringAmount": 29.99,
      "recurringAmountMinor": 2999,
      "initialInvoiceAmount": 14.5,
      "initialInvoiceAmountMinor": 1450
    }
  ]
}

InlineValidationError

A single validation problem reported on an entity, explaining what must be corrected. For example, orders return these for anything that blocks submission.

messagestringrequired

Validation error message.

propertystring

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

InlineValidationError
{
  "message": "Subscriber name is required.",
  "property": "subscriber.name"
}

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.
enum<string>

values

  • NOT_REQUIRED
  • OPTIONAL
  • REQUIRED
OrderRequirement
"NOT_REQUIRED"

SubscriptionListItem

Simplified subscription representation optimized for list operations. Use the detailed Subscription schema for individual subscription views.

subscriptionIdstringrequired

The unique identifier for the subscription.

statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
typestringrequired

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.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringrequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerIdstringrequired

The unique identifier for the customer who owns this subscription.

productOfferingIdstringrequired

The unique identifier for the product offering associated with this subscription.

subscriberIdstringrequired

The unique identifier for the subscriber associated with this subscription.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

SubscriptionListItem
{
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "status": "PENDING",
  "type": "CELL",
  "display": "(555) 123-4567",
  "msisdn": "+15551234567",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "activatedAt": "2024-01-15T10:30:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

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.

productOfferingIdstringrequired

The unique identifier for the product offering.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
productOfferingGroupIdstring

The unique identifier for the product offering group.

licenseIdstring

The unique identifier of the license associated with this add-on (if applicable).

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
SubscriptionAddonListItem
{
  "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "referenceId": "telna-package-12345",
  "status": "PENDING",
  "productOfferingGroupId": "extra-data-packages",
  "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
  "addedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T09:00:00Z",
  "cancelledAt": "2024-06-30T00:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

OrderModification

A modification applied to an existing service during order fulfillment.

typeenum<string>required

Type of modification applied.

values

  • SUBSCRIPTION_CHANGE
  • ADDON_CHANGE
targetIdstringrequired

The subscription or add-on that was modified.

newProductOfferingIdstring

The product offering the entity was changed to.

appliedAtstringdate-time

When the modification was applied.

OrderModification
{
  "type": "SUBSCRIPTION_CHANGE",
  "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "newProductOfferingId": "po_mobile_premium_plus",
  "appliedAt": "2024-01-15T15:00:00Z"
}

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.

orderIdstringrequired

Unique identifier for the order.

stateenum<string>required

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

  • PENDING
  • PENDING_PAYMENT
  • SUBMITTED
  • PENDING_APPROVAL
  • PROCESSING
  • COMPLETED
  • CANCELLED
  • EXPIRED
  • FAILED
userobject

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.

Show child attributes
userIdstring

The user's identifier, once the user exists.

namestring

The user's full name.

emailstringemail

The email the user logs in with.

newUserbooleanrequired

Whether this user is created as part of fulfilling the order.

customerobject

The 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
customerIdstring

The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
namestringrequired

Customer name.

newCustomerbooleanrequired

Indicates if the customer was/will be created as part of order fulfillment.

billingobject

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.

Show child attributes
namestring

Billing contact name.

emailstringemail

Billing contact email.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

shippingobject

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes
namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

promoCodestring

Promotional code applied to this order, if any.

paymentSessionIdstring

The payment session that collected payment for this order, set when the order was submitted with one.

paymentProfileSessionIdstring

The payment profile session used to set up a payment method for this order, set when the order was submitted with one.

signingSessionIdstring

The signing session that captured the customer's signature for this order, set when the order was submitted with one.

consentsobject with string keys

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.

Show child attributes
*string
lineItemsarray of OrderLineItemrequired

Line items in the order.

Show child attributes

Selected by type.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
pricingobject

Detailed pricing information for an order including taxes and discounts.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Subtotal after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64

Subtotal after discounts and before taxes and fees, in minor currency units. Add the totalDiscountsMinor of each line item to it to get the amount before discounts.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Tax amount for the order, in major currency units. Set to 0 for orders that will be invoiced separately.

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total amount due for the order, in major currency units.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

currencystringrequired

The ISO 4217 currency code for all pricing amounts (e.g., "USD").

recurringCostsobject

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

A discount that ends with the periods paid for up front is not applied here.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Recurring subtotal after discounts and before taxes, in major currency units.

subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total estimated recurring amount, in major currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on recurring charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on recurring charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

billingCycleobject

How often a recurring price is charged.

Show child attributes
initialInvoiceobject

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes
subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

First invoice subtotal (e.g., prorated amount, setup fees), in major currency units.

subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Total first invoice amount, in major currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Estimated tax on initial invoice charges, in major currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxAmountMinorintegerint64

Estimated tax on initial invoice charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether taxes are included in the total.

periodobject

Period covered by the initial invoice.

Show child attributes
calculatedAtstringdate-timerequired

When the pricing was last calculated.

lineItemsarray of OrderLineItemPricing

Pricing breakdown per line item.

Show child attributes
lineItemIdstringrequired

The line item in the order that this pricing applies to.

subtotalnumberdecimaldeprecated

Deprecated. Use subtotalMinor instead.

Amount for this line item after discounts and before taxes and fees, in major currency units.

subtotalMinorintegerint64required

Amount for this line item after discounts and before taxes and fees, in minor currency units. Add totalDiscountsMinor to it to get the amount before discounts.

totalnumberdecimaldeprecated

Deprecated. Use totalMinor instead.

Amount due for this line item after taxes, fees, and discounts, in major currency units.

totalMinorintegerint64required

Amount due for this line item after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

The individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.

Show child attributes
taxAmountnumberdecimaldeprecated

Deprecated. Use taxAmountMinor instead.

Total taxes for this line item, in major currency units.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of object

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount.

Show child attributes
totalDiscountsnumberdecimaldeprecated

Deprecated. Use totalDiscountsMinor instead.

Total discounts for this line item, in major currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountnumberdecimaldeprecated

Deprecated. Use recurringAmountMinor instead.

Recurring cost for this line item per billing cycle, in major currency units.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

initialInvoiceAmountnumberdecimaldeprecated

Deprecated. Use initialInvoiceAmountMinor instead.

Amount for this line item on the first invoice when different from recurring, in major currency units.

initialInvoiceAmountMinorintegerint64

Amount for this line item on the first invoice when different from recurring, in minor currency units.

validationobjectrequired

Validation status of the order and its line items.

Show child attributes
isValidbooleanrequired

Whether the order is valid and ready for submission.

missingFieldsarray of string

Required fields that are still missing.

errorsarray of InlineValidationError

Order-level validation errors.

Show child attributes
messagestringrequired

Validation error message.

propertystring

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

lineItemValidationarray of object

Validation status for each line item.

Show child attributes
lineItemIdstring

Reference to the line item.

isValidboolean

Whether this line item is valid.

missingFieldsarray of string

Required fields that are still missing.

errorsarray of InlineValidationError

Validation errors for this line item.

Show child attributes
requirementsobjectrequired

What this platform expects a checkout to collect before the order is submitted, so a client can build the right flow up front. These are declared per platform, not derived from the contents of the order.

Submit enforces what the order itself demands rather than what is declared here: an order with an amount left to collect is refused until that amount is paid, and an order that owes nothing submits without any payment reference.

Show child attributes
requiresPaymentenum<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_REQUIRED
  • OPTIONAL
  • REQUIRED
requiresPaymentProfileenum<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_REQUIRED
  • OPTIONAL
  • REQUIRED
requiresSigningenum<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_REQUIRED
  • OPTIONAL
  • REQUIRED
externalPaymentobject

External payment details if the order was paid outside the system.

Show child attributes
referencestring

Reference from the external payment system.

receiptDescriptionstring

Description of the external payment.

receiptUrlstringuri

URL to the external payment receipt.

receivedAtstringdate-time

When the external payment was recorded.

expiresAtstringdate-timerequired

When the order expires if not submitted (automatically refreshed on each order update to maintain active session).

submittedAtstringdate-time

When the order was submitted for fulfillment.

completedAtstringdate-time

When the order was completed.

createdEntitiesobject

Entities created as part of order fulfillment.

Show child attributes
subscriptionsarray of any

Subscriptions created during order fulfillment.

Show child attributes
subscriptionIdstringrequired

The unique identifier for the subscription.

statusenum<string>required

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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
typestringrequired

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.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringrequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

customerIdstringrequired

The unique identifier for the customer who owns this subscription.

productOfferingIdstringrequired

The unique identifier for the product offering associated with this subscription.

subscriberIdstringrequired

The unique identifier for the subscriber associated with this subscription.

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

createdByLineItemstringrequired

Line item ID that created this subscription.

addonsarray of any

Add-ons created during order fulfillment.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

statusenum<string>required

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

  • PENDING
  • ACTIVE
  • CANCELLED
  • EXPIRED
productOfferingGroupIdstring

The unique identifier for the product offering group.

licenseIdstring

The unique identifier of the license associated with this add-on (if applicable).

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

updatedAtstringdate-time

The date and time when the add-on was last updated.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
createdByLineItemstringrequired

Line item ID that created this add-on.

modificationsarray of any

Modifications applied during order fulfillment.

Show child attributes
typeenum<string>required

Type of modification applied.

values

  • SUBSCRIPTION_CHANGE
  • ADDON_CHANGE
targetIdstringrequired

The subscription or add-on that was modified.

newProductOfferingIdstring

The product offering the entity was changed to.

appliedAtstringdate-time

When the modification was applied.

createdByLineItemstringrequired

Line item ID that created this modification.

createdAtstringdate-timerequired

When the order was created.

updatedAtstringdate-timerequired

When the order was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
Order
{
  "orderId": "order-123",
  "state": "PENDING",
  "user": {
    "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "newUser": true
  },
  "customer": {
    "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "CONSUMER",
    "name": "John Doe",
    "newCustomer": true
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "instructions": "Leave at front door"
  },
  "promoCode": "STUDENT2024",
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
  "signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
  "consents": {
    "termsOfService": "true",
    "marketing": "true"
  },
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "msisdn": "+15551234567",
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "tempNumber": true,
      "portingRequested": true,
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "passcode": "123456",
          "firstName": "John",
          "lastName": "Doe",
          "address": {
            "street1": "500 S Main St",
            "street2": "Apt 1",
            "city": "Natick",
            "zip": "01701",
            "country": "US",
            "state": "CA",
            "region": "Ontario",
            "attention": "John Doe"
          }
        }
      },
      "extensions": {
        "propertyName": "string"
      },
      "display": "John Doe - Work phone",
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      },
      "sim": {
        "esim": true,
        "imei": "356938035643809",
        "iccid": "8931440400000000000"
      },
      "scheduleActivationAt": "2024-02-01",
      "activateOnDemand": true,
      "metadata": {
        "propertyName": "string"
      },
      "status": "PENDING"
    }
  ],
  "pricing": {
    "subtotal": 125.99,
    "subtotalMinor": 12599,
    "taxAmount": 10.08,
    "taxAmountMinor": 1008,
    "total": 137.39,
    "totalMinor": 13739,
    "taxIncluded": true,
    "currency": "USD",
    "recurringCosts": {
      "subtotal": 29.99,
      "subtotalMinor": 2999,
      "total": 32.39,
      "totalMinor": 3239,
      "taxAmount": 2.4,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "initialInvoice": {
      "subtotal": 14.5,
      "subtotalMinor": 1450,
      "total": 15.66,
      "totalMinor": 1566,
      "taxAmount": 1.16,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "period": {
        "start": "2024-01-15",
        "end": "2024-01-31"
      }
    },
    "calculatedAt": "2024-01-15T10:30:00Z",
    "lineItems": [
      {
        "lineItemId": "line-item-1",
        "subtotal": 29.99,
        "subtotalMinor": 2999,
        "total": 27.47,
        "totalMinor": 2747,
        "taxBreakdown": [
          {
            "description": "Sales Tax",
            "amount": 2.4,
            "amountMinor": 240,
            "rate": 8.25
          }
        ],
        "taxAmount": 2.47,
        "taxAmountMinor": 247,
        "taxIncluded": true,
        "discounts": [
          {
            "name": "First month free",
            "amount": 29.99,
            "amountMinor": 2999
          }
        ],
        "totalDiscounts": 29.99,
        "totalDiscountsMinor": 2999,
        "description": "Premium Plan",
        "recurringAmount": 29.99,
        "recurringAmountMinor": 2999,
        "initialInvoiceAmount": 14.5,
        "initialInvoiceAmountMinor": 1450
      }
    ]
  },
  "validation": {
    "isValid": false,
    "missingFields": [
      "customer",
      "billing.address"
    ],
    "errors": [
      {
        "message": "Subscriber name is required.",
        "property": "subscriber.name"
      }
    ],
    "lineItemValidation": [
      {
        "lineItemId": "line-item-1",
        "isValid": false,
        "missingFields": [
          "subscriber.name",
          "sim.iccid"
        ],
        "errors": [
          {
            "message": "Subscriber name is required.",
            "property": "subscriber.name"
          }
        ]
      }
    ]
  },
  "requirements": {
    "requiresPayment": "NOT_REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "externalPayment": {
    "reference": "ext-payment-ref-123",
    "receiptDescription": "Payment via external billing system",
    "receiptUrl": "https://external.example.com/receipts/123",
    "receivedAt": "2024-01-15T14:30:00Z"
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "submittedAt": "2024-01-15T14:30:00Z",
  "completedAt": "2024-01-15T15:00:00Z",
  "createdEntities": {
    "subscriptions": [
      {
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "status": "PENDING",
        "type": "CELL",
        "display": "(555) 123-4567",
        "msisdn": "+15551234567",
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
        "activatedAt": "2024-01-15T10:30:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "createdAt": "2024-01-10T08:00:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "addons": [
      {
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "referenceId": "telna-package-12345",
        "status": "PENDING",
        "productOfferingGroupId": "extra-data-packages",
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "addedAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T09:00:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "metadata": {
          "propertyName": "string"
        },
        "createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "modifications": [
      {
        "type": "SUBSCRIPTION_CHANGE",
        "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "newProductOfferingId": "po_mobile_premium_plus",
        "appliedAt": "2024-01-15T15:00:00Z",
        "createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ]
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

UpdateOrderRequest

Request to update order details (excludes line items).

userone of

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.

Show child attributes
userIdstringrequired

The user's internal ID.

authenticatedUserbooleanrequired

Always true.

namestringrequired

The user's full name.

emailstringemailrequired

The email the user logs in with and receives order confirmations on.

identitystring

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.

msisdnstringphone

The user's phone number.

addressobject

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 keys

A set of key-value pairs that can be attached to an object 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
customerone of

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.

Show child attributes
customerIdstringrequired

The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically.

authenticatedCustomerbooleanrequired

Always true.

referenceIdstringmax length 255

Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one.

namestringrequired

Name for the new customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

  • CONSUMER
  • BUSINESS
identitystring

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.

preferredLocalestring

Preferred locale for the customer.

contactobject

Contact information for the new customer.

Show child attributes
billingobject

Billing configuration and payment preferences for the new customer.

Show child attributes
metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
billingobject

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.

Show child attributes
namestring

Billing contact name.

emailstringemail

Billing contact email.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

shippingobject

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes
namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

consentsobject with string keys

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.

Show child attributes
*string
promoCodestring

Promo code to apply to the order, or an empty string to remove the one it holds. Rejected with promo_code_not_redeemable when no promotion has that code, or when it is outside its validity period.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
UpdateOrderRequest
{
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    },
    "instructions": "Leave at front door"
  },
  "consents": {
    "termsOfService": "true",
    "marketing": "true"
  },
  "promoCode": "STUDENT2024",
  "metadata": {
    "propertyName": "string"
  }
}

AddLineItemRequest

Request to add a line item to an order.

lineItemone ofrequired

A line item in an order representing a billable action or service.

Show child attributes

Selected by type.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
AddLineItemRequest
{
  "lineItem": {
    "type": "SUBSCRIPTION",
    "lineItemId": "line-item-1",
    "productOfferingId": "mobile-plan-basic",
    "msisdn": "+15551234567",
    "leaseToken": "lease_8f3b1c2d4e5f6789",
    "tempNumber": true,
    "portingRequested": true,
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "extensions": {
      "propertyName": "string"
    },
    "display": "John Doe - Work phone",
    "subscriber": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "msisdn": "+15551234567",
      "address": {
        "street1": "500 S Main St",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      }
    },
    "sim": {
      "esim": true,
      "imei": "356938035643809",
      "iccid": "8931440400000000000"
    },
    "scheduleActivationAt": "2024-02-01",
    "activateOnDemand": true,
    "metadata": {
      "propertyName": "string"
    },
    "status": "PENDING"
  }
}

UpdateLineItemRequest

Request to update a line item configuration.

lineItemone ofrequired

A line item in an order representing a billable action or service.

Show child attributes

Selected by type.

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

  • SUBSCRIPTION
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The product offering to create a subscription for.

msisdnstring

The phone number for this subscription.

  • Leave empty to have one assigned.
  • When the number pool is available, you can choose a number from the pool and provide the leaseToken.
  • When porting a number, provide the number and porting details.
leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

portingRequestedboolean

If true, the number is a port-in.

portingobject

Details needed to port in a number for this subscription.

Show child attributes
extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes
displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
simobject

The choice between eSIM and physical SIM plus related device details. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes
scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

  • ADDON
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The add-on product offering to add.

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

scheduledAtstringdate

When to activate the add-on.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

  • EXTERNAL_PRODUCT
lineItemIdstringrequired

Unique identifier for this line item within the order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

  • EXTERNAL
lineItemIdstringrequired

Unique identifier for this line item within the order.

namestringrequired

Name of the external item.

descriptionstring

Description of the external item.

priceobjectrequired

Custom pricing for the external item.

Show child attributes
quantityinteger>= 1

Quantity of the external item.

taxationIdstring

US taxation ID for tax calculation.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

parentLineItemIdstring

Reference to parent line item in this order.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing subscription. Always SUBSCRIPTION_CHANGE.

values

  • SUBSCRIPTION_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The identifier of the existing subscription whose product offering this line item changes.

productOfferingIdstringrequired

New product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
typeenum<string>required

Identifies this line item as a product offering change for an existing add-on. Always ADDON_CHANGE.

values

  • ADDON_CHANGE
lineItemIdstringrequired

Unique identifier for this line item within the order.

subscriptionIdstringrequired

The subscription containing the add-on to modify.

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

productOfferingIdstringrequired

New add-on product offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
statusenum<string>

Server-resolved fulfillment status for this line item.

The current fulfillment status of an order line item.

Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order.

values

  • PENDING
  • RUNNING
  • COMPLETED
  • FAILED
UpdateLineItemRequest
{
  "lineItem": {
    "type": "SUBSCRIPTION",
    "lineItemId": "line-item-1",
    "productOfferingId": "mobile-plan-basic",
    "msisdn": "+15551234567",
    "leaseToken": "lease_8f3b1c2d4e5f6789",
    "tempNumber": true,
    "portingRequested": true,
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "passcode": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "street1": "500 S Main St",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      }
    },
    "extensions": {
      "propertyName": "string"
    },
    "display": "John Doe - Work phone",
    "subscriber": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "msisdn": "+15551234567",
      "address": {
        "street1": "500 S Main St",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      }
    },
    "sim": {
      "esim": true,
      "imei": "356938035643809",
      "iccid": "8931440400000000000"
    },
    "scheduleActivationAt": "2024-02-01",
    "activateOnDemand": true,
    "metadata": {
      "propertyName": "string"
    },
    "status": "PENDING"
  }
}

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).

paymentSessionIdstring

Reference to completed payment session for orders requiring payment collection.

paymentProfileSessionIdstring

Reference to completed payment profile session for zero-total orders requiring payment method setup.

signingSessionIdstring

Reference to completed signing session.

externalPaymentobject

Details of an external payment made outside the system. When provided, the order is considered paid and will bypass internal payment requirements.

Cannot be used together with paymentSessionId.

Show child attributes
referencestringmin length 1required

Reference or identifier from the external payment system.

receiptDescriptionstring

Optional human-readable description of the payment.

receiptUrlstringuri

Optional URL to a receipt or confirmation page for the payment.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
SubmitOrderRequest
{
  "paymentSessionId": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
  "paymentProfileSessionId": "b2c3d4e5-f6a7-8901-2345-6789abcdef01",
  "signingSessionId": "c3d4e5f6-a7b8-9012-3456-789abcdef012",
  "externalPayment": {
    "reference": "ext-payment-ref-123",
    "receiptDescription": "Payment via external billing system",
    "receiptUrl": "https://external.example.com/receipts/123"
  },
  "metadata": {
    "propertyName": "string"
  }
}

ApproveOrderRequest

Approve an order that requires admin or manager approval before fulfillment can proceed.

commentstringmax length 1000

Optional comment explaining the approval decision.

ApproveOrderRequest
{
  "comment": "Approved after reviewing customer credit check"
}

InvoiceStatus

Current stage of the invoice lifecycle.

  • DRAFT: Being prepared; not yet visible to the customer.
  • SENT: Delivered to the customer and awaiting payment.
  • PAID: Payment has been received.
  • VOID: Canceled and no longer collectible.
  • OVERDUE: Past its due date without payment.
enum<string>

values

  • DRAFT
  • SENT
  • PAID
  • VOID
  • OVERDUE
InvoiceStatus
"DRAFT"

InvoiceListItem

An invoice summary without its line items, optimized for list views. Fetch the individual invoice for the full line item breakdown.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice is for.

invoiceNumberstringrequired

Human-readable invoice number.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

  • DRAFT: Being prepared; not yet visible to the customer.
  • SENT: Delivered to the customer and awaiting payment.
  • PAID: Payment has been received.
  • VOID: Canceled and no longer collectible.
  • OVERDUE: Past its due date without payment.

values

  • DRAFT
  • SENT
  • PAID
  • VOID
  • OVERDUE
dueDatestringdaterequired

When payment is due.

subtotalAmountMinorintegerint64

Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

totalAmountMinorintegerint64

Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.

currencystring

The ISO 4217 currency code for all invoice amounts (e.g., "USD").

sentAtstringdate-time

When the invoice was sent to the customer (if status is sent or later).

paidAtstringdate-time

When the invoice was paid (if status is paid).

voidedAtstringdate-time

When the invoice was voided (if status is void).

invoiceUrlstringuri

Hosted URL where customer can view the invoice.

createdAtstringdate-timerequired

When the invoice was created.

updatedAtstringdate-timerequired

When the invoice was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
InvoiceListItem
{
  "invoiceId": "094f10ca-616e-441c-b264-9a2305d6692d",
  "customerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "invoiceNumber": "INV-2024-001",
  "status": "SENT",
  "dueDate": "2024-02-15",
  "subtotalAmountMinor": 2999,
  "totalAmountMinor": 2989,
  "currency": "USD",
  "sentAt": "2024-01-15T10:00:00Z",
  "paidAt": "2024-02-10T14:30:00Z",
  "voidedAt": "2024-02-05T09:00:00Z",
  "invoiceUrl": "https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

InvoiceLineItem

Individual line item within an invoice, showing detailed pricing breakdown.

descriptionstringrequired

Description of what this line item represents.

subscriptionIdstring

ID of the subscription this line item is associated with, if applicable.

licenseIdstring

ID of the license this line item is associated with, if applicable.

productOfferingIdstring

ID of the product offering this line item is associated with, if applicable.

quantityinteger>= 1

Quantity of items for this line item.

unitPriceMinorintegerint64

Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

subtotalMinorintegerint64required

Line item subtotal (quantity x unitPriceMinor), in minor currency units.

totalMinorintegerint64required

Line item total after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

Tax breakdown for this line item.

Show child attributes
descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

The amount charged for this tax component, in major units of the currency of the transaction.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

feesarray of object

Detailed fee breakdown for this line item.

Show child attributes
namestringrequired

Fee name or description.

amountMinorintegerint64required

Fee amount, in minor currency units.

totalFeesMinorintegerint64

Total fees for this line item, in minor currency units.

discountsarray of object

Detailed discount breakdown for this line item.

Show child attributes
namestringrequired

Discount name or description.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

InvoiceLineItem
{
  "description": "Mobile subscription - Premium Plan",
  "subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
  "productOfferingId": "mobile-plan-premium",
  "quantity": 1,
  "unitPriceMinor": 2999,
  "subtotalMinor": 2999,
  "totalMinor": 3739,
  "taxBreakdown": [
    {
      "description": "Sales Tax",
      "amount": 2.4,
      "amountMinor": 240,
      "rate": 8.25
    }
  ],
  "taxAmountMinor": 240,
  "taxIncluded": false,
  "fees": [
    {
      "name": "Late payment fee",
      "amountMinor": 1000
    }
  ],
  "totalFeesMinor": 1000,
  "discounts": [
    {
      "name": "Volume discount",
      "amountMinor": 500
    }
  ],
  "totalDiscountsMinor": 500
}

Invoice

An invoice with detailed line item breakdown that can be sent to customers for payment.

invoiceIdstringrequired

Unique identifier for the invoice.

customerIdstringrequired

The customer this invoice is for.

invoiceNumberstringrequired

Human-readable invoice number.

statusenum<string>required

Current status of the invoice.

Current stage of the invoice lifecycle.

  • DRAFT: Being prepared; not yet visible to the customer.
  • SENT: Delivered to the customer and awaiting payment.
  • PAID: Payment has been received.
  • VOID: Canceled and no longer collectible.
  • OVERDUE: Past its due date without payment.

values

  • DRAFT
  • SENT
  • PAID
  • VOID
  • OVERDUE
dueDatestringdaterequired

When payment is due.

lineItemsarray of InvoiceLineItemrequired

Detailed breakdown of items included in this invoice.

Show child attributes
descriptionstringrequired

Description of what this line item represents.

subscriptionIdstring

ID of the subscription this line item is associated with, if applicable.

licenseIdstring

ID of the license this line item is associated with, if applicable.

productOfferingIdstring

ID of the product offering this line item is associated with, if applicable.

quantityinteger>= 1

Quantity of items for this line item.

unitPriceMinorintegerint64

Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

subtotalMinorintegerint64required

Line item subtotal (quantity x unitPriceMinor), in minor currency units.

totalMinorintegerint64required

Line item total after taxes, fees, and discounts, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

Tax breakdown for this line item.

Show child attributes
descriptionstringrequired

Human-readable name of the tax or fee, suitable for display on invoices and receipts.

amountnumberdecimaldeprecated

Deprecated. Use amountMinor instead.

The amount charged for this tax component, in major units of the currency of the transaction.

amountMinorintegerint64required

The amount charged for this tax component, in minor units of the currency of the transaction.

ratenumberdecimal

The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

feesarray of object

Detailed fee breakdown for this line item.

Show child attributes
namestringrequired

Fee name or description.

amountMinorintegerint64required

Fee amount, in minor currency units.

totalFeesMinorintegerint64

Total fees for this line item, in minor currency units.

discountsarray of object

Detailed discount breakdown for this line item.

Show child attributes
namestringrequired

Discount name or description.

amountMinorintegerint64required

Discount amount (positive value), in minor currency units.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

subtotalAmountMinorintegerint64

Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).

taxAmountMinorintegerint64

Total tax amount for the invoice, in minor currency units.

feeAmountMinorintegerint64

Total fee amount for the invoice, in minor currency units.

discountAmountMinorintegerint64

Total amount deducted by discounts (positive value), in minor currency units.

totalAmountMinorintegerint64

Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.

currencystring

The ISO 4217 currency code for all invoice amounts (e.g., "USD").

sentAtstringdate-time

When the invoice was sent to the customer (if status is sent or later).

paidAtstringdate-time

When the invoice was paid (if status is paid).

voidedAtstringdate-time

When the invoice was voided (if status is void).

invoiceUrlstringuri

Hosted URL where customer can view the invoice.

createdAtstringdate-timerequired

When the invoice was created.

updatedAtstringdate-timerequired

When the invoice was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
Invoice
{
  "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "456789ab-cdef-0123-4567-89abcdef0123",
  "invoiceNumber": "INV-2024-001",
  "status": "SENT",
  "dueDate": "2024-02-15",
  "lineItems": [
    {
      "description": "Mobile subscription - Premium Plan",
      "subscriptionId": "b8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "productOfferingId": "mobile-plan-premium",
      "quantity": 1,
      "unitPriceMinor": 2999,
      "subtotalMinor": 2999,
      "totalMinor": 3739,
      "taxBreakdown": [
        {
          "description": "Sales Tax",
          "amount": 2.4,
          "amountMinor": 240,
          "rate": 8.25
        }
      ],
      "taxAmountMinor": 240,
      "taxIncluded": false,
      "fees": [
        {
          "name": "Late payment fee",
          "amountMinor": 1000
        }
      ],
      "totalFeesMinor": 1000,
      "discounts": [
        {
          "name": "Volume discount",
          "amountMinor": 500
        }
      ],
      "totalDiscountsMinor": 500
    }
  ],
  "subtotalAmountMinor": 2999,
  "taxAmountMinor": 240,
  "feeAmountMinor": 250,
  "discountAmountMinor": 500,
  "totalAmountMinor": 2989,
  "currency": "USD",
  "sentAt": "2024-01-15T10:00:00Z",
  "paidAt": "2024-02-10T14:30:00Z",
  "voidedAt": "2024-02-05T09:00:00Z",
  "invoiceUrl": "https://invoices.yourapp.com/inv_123e4567",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

MarkInvoiceAsPaidRequest

Request to mark an invoice as paid when you manage your own payment processing.

paidAtstringdate-time

When the payment was received. If not provided, uses the current timestamp.

metadataobject with string keys

Metadata to attach to the invoice.

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
MarkInvoiceAsPaidRequest
{
  "paidAt": "2024-02-10T14:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

PaymentLinkStatus

Current status of a payment link.

  • ACTIVE: The link is open and the customer can complete payment.
  • EXPIRED: The link expired before payment was completed.
  • COMPLETED: Payment through the link succeeded.
  • CANCELED: The link was canceled and can no longer be used.
  • FAILED: Payment through the link failed.
enum<string>

values

  • ACTIVE
  • EXPIRED
  • COMPLETED
  • CANCELED
  • FAILED
PaymentLinkStatus
"ACTIVE"

PaymentProvider

Payment service provider that processes the transaction.

enum<string>

ExampleSTRIPE

values

  • STRIPE
  • BILLOGRAM
PaymentProvider
"STRIPE"

PaymentLink

A shareable hosted payment page that collects payment for an order at the customer's convenience. Create one when the customer is not in an active checkout flow — for example to send by email or SMS — and anyone with the URL can complete the payment.

Use a payment session instead when the customer is present in your checkout and should be redirected to pay immediately. Both collect against the order's underlying payment intent, which records the resulting charges and refunds.

paymentLinkIdstringrequired

Unique identifier for the payment link.

orderIdstring

The order this payment link collects payment for.

customerIdstring

The customer this payment link collects payment from.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

The saved payment method pre-selected for the customer, if any.

hostedUrlstringurirequired

The URL where customers can complete their payment.

statusenum<string>required

Current status of a payment link.

  • ACTIVE: The link is open and the customer can complete payment.
  • EXPIRED: The link expired before payment was completed.
  • COMPLETED: Payment through the link succeeded.
  • CANCELED: The link was canceled and can no longer be used.
  • FAILED: Payment through the link failed.

values

  • ACTIVE
  • EXPIRED
  • COMPLETED
  • CANCELED
  • FAILED
descriptionstring

Optional description displayed on the payment page.

paymentIntentIdstring

The payment intent that collected the payment, available once the link has been paid.

completedAtstringdate-time

When the payment was completed, if the link has been paid.

createdAtstringdate-timerequired

When the payment link was created.

updatedAtstringdate-timerequired

When the payment link was last updated.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
PaymentLink

CreatePaymentLinkRequest

Request to create a new payment link for processing payment for an order or invoice. Either orderId or invoiceId must be provided, not both.

orderIdstring

The unique identifier of the order to create a payment link for. Either orderId or invoiceId must be provided, not both.

invoiceIdstring

The unique identifier of the invoice to create a payment link for. Either orderId or invoiceId must be provided, not both. Invoice payment links are not yet available in all environments.

paymentProfileIdstring

A previously saved payment method to prefill on the payment page, for returning customers.

savePaymentProfileboolean

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

setAsDefaultPaymentProfileboolean

Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.

descriptionstring

Optional description to display on the payment page.

grantAutopayConsentboolean

Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.

returnUrlstringuri

URL to redirect customers to after successful payment.

cancelUrlstringuri

URL to redirect customers to if they cancel the payment.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreatePaymentLinkRequest
{
  "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "invoiceId": "123e4567-e89b-12d3-a456-426614174000",
  "paymentProfileId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "savePaymentProfile": true,
  "setAsDefaultPaymentProfile": false,
  "description": "Payment for Telness mobile subscription",
  "grantAutopayConsent": false,
  "returnUrl": "https://your-domain.com/success",
  "cancelUrl": "https://your-domain.com/cancel",
  "metadata": {
    "propertyName": "string"
  }
}

PaymentIntentStatus

Current stage of a payment intent as it is collected through the payment provider.

  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.
enum<string>

ExampleSUCCEEDED

values

  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
PaymentIntentStatus
"SUCCEEDED"

PaymentIntentListItem

A payment intent without its nested attempts, refunds, and line items, optimized for list views.

paymentIntentIdstringrequired

The unique identifier for this payment intent.

customerIdstringrequired

The customer this payment intent collects from.

statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

descriptionstring

A human-readable description of what is being collected.

dueAtstringdate-time

When the amount is due.

createdAtstringdate-timerequired

When the payment intent was created.

updatedAtstringdate-timerequired

When the payment intent was last updated.

PaymentIntentListItem
{
  "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "SUCCEEDED",
  "amountMinor": 2900,
  "currency": "USD",
  "description": "Mobile subscription renewal",
  "dueAt": "2024-01-15T10:00:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

PaymentIntentLineItem

A single billed item contributing to a payment intent's amount.

descriptionstringrequired

What this line item represents.

amountMinorintegerint64required

The base cost of the line item before discounts and taxes, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD).

subscriptionIdstring

The subscription this line item is associated with, if any.

licenseIdstring

The license this line item is associated with, if any.

discountsarray of object

Discounts applied to this line item.

Show child attributes
descriptionstringrequired

What the discount is for.

amountMinorintegerint64required

The discounted amount (positive value), in minor units of the payment intent's currency.

taxesarray of object

Taxes applied to this line item.

Show child attributes
descriptionstringrequired

The tax component applied (e.g., a named tax and its rate).

amountMinorintegerint64required

The tax amount, in minor units of the payment intent's currency.

PaymentIntentLineItem
{
  "description": "Mobile subscription - Premium Plan",
  "amountMinor": 2900,
  "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
  "discounts": [
    {
      "description": "Loyalty discount",
      "amountMinor": 500
    }
  ],
  "taxes": [
    {
      "description": "VAT 25%",
      "amountMinor": 725
    }
  ]
}

PaymentAttempt

A single charge attempt against a payment intent.

paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

amountMinorintegerint64required

The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the attempt was charged in (e.g., "USD").

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
reasonstring

Failure reason when the attempt did not succeed.

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

PaymentAttempt
{
  "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
  "amountMinor": 2900,
  "currency": "USD",
  "result": "SUCCEEDED",
  "reason": "card_declined",
  "chargedAt": "2024-01-15T10:00:00Z",
  "createdAt": "2024-01-15T10:00:00Z"
}

PaymentRefund

A refund issued against a payment intent.

refundIdstringrequired

The unique identifier for this refund.

amountMinorintegerint64required

The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the refund is issued in (e.g., "USD").

reasonenum<string>

Why the refund was issued.

values

  • UNKNOWN
  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
createdAtstringdate-timerequired

When the refund was created.

PaymentRefund
{
  "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
  "amountMinor": 2900,
  "currency": "USD",
  "reason": "REQUESTED_BY_CUSTOMER",
  "status": "SUCCEEDED",
  "createdAt": "2024-01-15T10:00:00Z"
}

PaymentIntent

The record of an amount being collected from a customer over card rails, with the charge attempts, refunds, and billed line items that show how collection went.

A payment intent is created automatically when payment collection starts for an order, whether through a payment session or a payment link; you do not create one directly. Read it to see what was charged, retried, or refunded. To start collecting payment, create a payment session (customer present in your checkout) or a payment link (shareable hosted page) instead.

paymentIntentIdstringrequired

The unique identifier for this payment intent.

customerIdstringrequired

The customer this payment intent collects from.

statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

descriptionstring

A human-readable description of what is being collected.

dueAtstringdate-time

When the amount is due.

lineItemsarray of PaymentIntentLineItemrequired

The items that make up the collected amount.

Show child attributes
descriptionstringrequired

What this line item represents.

amountMinorintegerint64required

The base cost of the line item before discounts and taxes, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD).

subscriptionIdstring

The subscription this line item is associated with, if any.

licenseIdstring

The license this line item is associated with, if any.

discountsarray of object

Discounts applied to this line item.

Show child attributes
descriptionstringrequired

What the discount is for.

amountMinorintegerint64required

The discounted amount (positive value), in minor units of the payment intent's currency.

taxesarray of object

Taxes applied to this line item.

Show child attributes
descriptionstringrequired

The tax component applied (e.g., a named tax and its rate).

amountMinorintegerint64required

The tax amount, in minor units of the payment intent's currency.

attemptsarray of PaymentAttemptrequired

Charge attempts made against this payment intent, most recent first.

Show child attributes
paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

amountMinorintegerint64required

The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the attempt was charged in (e.g., "USD").

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
reasonstring

Failure reason when the attempt did not succeed.

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

refundsarray of PaymentRefundrequired

Refunds issued against this payment intent.

Show child attributes
refundIdstringrequired

The unique identifier for this refund.

amountMinorintegerint64required

The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

currencystringrequired

The ISO 4217 currency code the refund is issued in (e.g., "USD").

reasonenum<string>

Why the refund was issued.

values

  • UNKNOWN
  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
createdAtstringdate-timerequired

When the refund was created.

createdAtstringdate-timerequired

When the payment intent was created.

updatedAtstringdate-timerequired

When the payment intent was last updated.

PaymentIntent
{
  "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "SUCCEEDED",
  "amountMinor": 2900,
  "currency": "USD",
  "description": "Mobile subscription renewal",
  "dueAt": "2024-01-15T10:00:00Z",
  "lineItems": [
    {
      "description": "Mobile subscription - Premium Plan",
      "amountMinor": 2900,
      "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "discounts": [
        {
          "description": "Loyalty discount",
          "amountMinor": 500
        }
      ],
      "taxes": [
        {
          "description": "VAT 25%",
          "amountMinor": 725
        }
      ]
    }
  ],
  "attempts": [
    {
      "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
      "amountMinor": 2900,
      "currency": "USD",
      "result": "SUCCEEDED",
      "reason": "card_declined",
      "chargedAt": "2024-01-15T10:00:00Z",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "refunds": [
    {
      "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
      "amountMinor": 2900,
      "currency": "USD",
      "reason": "REQUESTED_BY_CUSTOMER",
      "status": "SUCCEEDED",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

CreatePaymentSessionRequest

Request to create a new payment session for processing payment for an order.

orderIdstringrequired

The unique identifier of the order to create a payment session for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

A previously saved payment method to prefill on the payment page, for returning customers.

savePaymentProfileboolean

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

setAsDefaultPaymentProfileboolean

Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.

grantAutopayConsentboolean

Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.

hostedboolean

Whether to create a hosted checkout session. Currently all payment sessions use the hosted checkout flow, so a hosted payment page URL is always returned regardless of this value.

returnUrlstringrequired

The URL the customer is redirected to after completing payment on the hosted page. Must be provided to create a session.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment on the hosted page.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreatePaymentSessionRequest
{
  "orderId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "savePaymentProfile": true,
  "setAsDefaultPaymentProfile": false,
  "grantAutopayConsent": false,
  "hosted": true,
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "metadata": {
    "propertyName": "string"
  }
}

PaymentSessionStatus

Current status of a payment session lifecycle.

enum<string>

ExamplePENDING

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
  • EXPIRED
PaymentSessionStatus
"PENDING"

PaymentSession

A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow and redirect the customer to hostedUrl to pay; once the session completes, pass its paymentSessionId when submitting the order.

Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds.

paymentSessionIdstringrequired

The unique identifier for this payment session.

orderIdstringrequired

The unique identifier of the order this payment session is for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

The saved payment method to use for this payment (for returning customers).

savePaymentProfilebooleanrequired

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

hostedUrlstringurirequired

The hosted checkout page to redirect the customer to in order to complete payment.

returnUrlstring

The URL the customer is redirected to after payment completion.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment.

statusenum<string>required

Current status of a payment session lifecycle.

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
  • EXPIRED
metadataobject with string keysrequired

Custom key-value pairs for additional payment session information.

Show child attributes
*string
createdAtstringdate-timerequired

When this payment session was created.

updatedAtstringdate-timerequired

When this payment session was last updated.

PaymentSession
{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
  "savePaymentProfile": true,
  "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "status": "PENDING",
  "metadata": {
    "source": "mobile_app",
    "campaign": "summer_2024"
  },
  "createdAt": "2024-09-29T10:00:00Z",
  "updatedAt": "2024-09-29T10:30:00Z"
}

CancelPaymentSessionRequest

Request to cancel an active payment session.

reasonstring

Optional reason for cancelling the payment session.

metadataobject with string keys

Custom key-value pairs for additional cancellation information.

Show child attributes
*string
CancelPaymentSessionRequest
{
  "reason": "Customer changed their mind",
  "metadata": {
    "cancelled_by": "customer_service",
    "ticket_id": "SUPP-12345"
  }
}

PaymentMethodType

The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change.

string

ExampleCARD

PaymentMethodType
"CARD"

PaymentProfileStatus

Whether a saved payment profile can currently be charged.

  • ACTIVE: The payment method is valid and can be used for payments.
  • INACTIVE: The payment method has been deactivated and cannot be charged.
  • EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced.
  • REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again.
enum<string>

values

  • ACTIVE
  • INACTIVE
  • EXPIRED
  • REQUIRES_ACTION
PaymentProfileStatus
"ACTIVE"

EmbeddedPaymentProfile

A saved payment method with only the details needed to display it in a list, without billing information.

paymentProfileIdstringrequired

Unique identifier for this payment profile.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
typestringrequired

Type of payment method.

The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change.

statusenum<string>required

Current status of the payment profile.

Whether a saved payment profile can currently be charged.

  • ACTIVE: The payment method is valid and can be used for payments.
  • INACTIVE: The payment method has been deactivated and cannot be charged.
  • EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced.
  • REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again.

values

  • ACTIVE
  • INACTIVE
  • EXPIRED
  • REQUIRES_ACTION
displayNamestring

Human-readable name for the payment method, safe to show to the customer:

  • Card: "Visa ending in 4242"
  • SEPA: "Bank account ending in 3000"
  • Swish: "Swish +46701234567"
isDefaultboolean

Whether this is the customer's default payment profile.

expiresAtstringdate

When this payment profile expires (for cards).

createdAtstringdate-timerequired

When this payment profile was created.

EmbeddedPaymentProfile
{
  "paymentProfileId": "f6a7b8c9-d0e1-2345-6789-abcdef012345",
  "paymentProvider": "STRIPE",
  "type": "CARD",
  "status": "ACTIVE",
  "displayName": "Visa ending in 4242",
  "isDefault": true,
  "expiresAt": "2025-12-31",
  "createdAt": "2024-01-15T10:00:00Z"
}

PaymentProfile

A saved payment method or mandate for future use.

paymentProfileIdstringrequired

Unique identifier for this payment profile.

paymentProviderenum<string>

The payment provider for this payment profile.

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
typestringrequired

Type of payment method.

The kind of payment method, as reported by the payment provider. This is an open set of provider-defined values (for example "CARD", "SEPA_DEBIT", "SWISH", "VIPPS", "KLARNA", "PAYPAL") rather than a fixed enumeration, so new method types can appear without an API change.

statusenum<string>required

Current status of the payment profile.

Whether a saved payment profile can currently be charged.

  • ACTIVE: The payment method is valid and can be used for payments.
  • INACTIVE: The payment method has been deactivated and cannot be charged.
  • EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced.
  • REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again.

values

  • ACTIVE
  • INACTIVE
  • EXPIRED
  • REQUIRES_ACTION
customerIdstringrequired

Customer who owns this payment profile.

displayNamestring

Human-readable name for this payment method.

expiresAtstringdate

When this payment profile expires (for cards).

billingDetailsobject

Billing details associated with this payment method.

Show child attributes
namestring

Billing name.

emailstringemail

Billing email.

addressobject

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

createdAtstringdate-timerequired

When this payment profile was created.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
PaymentProfile
{
  "paymentProfileId": "d9f0b83a-8b0d-44a6-af7c-54b6b91b6040",
  "paymentProvider": "STRIPE",
  "type": "CARD",
  "status": "ACTIVE",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "displayName": "My credit card",
  "expiresAt": "2025-12-31",
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

CreatePaymentProfileSessionRequest

Request to create a new payment profile session for setting up a saved payment method.

orderIdstringrequired

The unique identifier of the order this payment profile session is associated with.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
returnUrlstringrequired

The URL the customer is redirected to after the payment method is saved.

cancelUrlstring

The URL the customer is redirected to if they cancel before saving a payment method.

setAsDefaultPaymentProfileboolean

Whether to set the saved payment method as the customer's default for future payments. Defaults to false.

metadataobject with string keys

A set of key-value pairs that can be attached to an object 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
CreatePaymentProfileSessionRequest
{
  "orderId": "9f8e7d6c-5b4a-3210-9876-543210987654",
  "paymentProvider": "STRIPE",
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "setAsDefaultPaymentProfile": false,
  "metadata": {
    "propertyName": "string"
  }
}

PaymentProfileSessionStatus

Current status of a payment profile session lifecycle.

enum<string>

ExamplePENDING

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
PaymentProfileSessionStatus
"PENDING"

PaymentProfileSession

A session that walks the customer through setting up and saving a payment method for future billing, without charging them. Create one when an order requires a payment profile but no upfront payment (e.g., a zero-total order), redirect the customer to hostedUrl, and pass the completed session's paymentProfileSessionId when submitting the order. To collect an actual payment, create a payment session instead.

paymentProfileSessionIdstringrequired

The unique identifier for this payment profile session.

orderIdstringrequired

The unique identifier of the order this payment profile session is associated with.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
statusenum<string>required

Current status of a payment profile session lifecycle.

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
hostedUrlstringurirequired

The hosted page to redirect the customer to in order to save their payment method.

metadataobject with string keysrequired

Custom key-value pairs for additional payment profile session information.

Show child attributes
*string
createdAtstringdate-timerequired

When this payment profile session was created.

updatedAtstringdate-timerequired

When this payment profile session was last updated.

PaymentProfileSession
{
  "paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
  "orderId": "44567801-a504-4f09-8089-31ea78bc239b",
  "paymentProvider": "STRIPE",
  "status": "PENDING",
  "hostedUrl": "https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2",
  "metadata": {
    "source": "mobile_app",
    "campaign": "summer_2024"
  },
  "createdAt": "2024-09-29T10:00:00Z",
  "updatedAt": "2024-09-29T10:30:00Z"
}

CancelPaymentProfileSessionRequest

Request to cancel an active payment profile session.

reasonstring

Optional reason for cancelling the payment profile session.

metadataobject with string keys

Custom key-value pairs for additional cancellation information.

Show child attributes
*string
CancelPaymentProfileSessionRequest
{
  "reason": "Customer decided not to save payment method",
  "metadata": {
    "cancelled_by": "customer_service",
    "ticket_id": "SUPP-12345"
  }
}

SigningStatus

The current status of a signing session.

enum<string>

values

  • PENDING
  • IN_PROGRESS
  • COMPLETED
  • FAILED
  • EXPIRED
  • CANCELLED
SigningStatus
"PENDING"

SigningSession

A contract signing session for an order requiring legal signature.

signingSessionIdstringrequired

The unique identifier for this signing session.

orderIdstringrequired

The order that requires signing.

statusenum<string>required

The current status of a signing session.

values

  • PENDING
  • IN_PROGRESS
  • COMPLETED
  • FAILED
  • EXPIRED
  • CANCELLED
signerDetailsobject with string keysrequired

Information about the person signing the contract.

The specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider.

Show child attributes
*string
providerstring

The signing provider used for this session.

languagestringdefault en

The language used for the signing interface.

redirectUrlstringuri

The URL where the user should be redirected to complete signing.

returnUrlstringuri

The URL where the user will be redirected after signing completion.

documentUrlstringuri

Download URL for the signed contract. Only available when status is COMPLETED.

completedAtstringdate-time

When the signing was completed. Only present when status is COMPLETED.

expiresAtstringdate-time

When this signing session expires.

failureReasonstring

The reason for signing failure. Only present when status is FAILED.

createdAtstringdate-timerequired

When the signing session was created.

metadataobject with string keys

Additional metadata for the signing session.

Show child attributes
*string
SigningSession
{
  "signingSessionId": "f7d2295f-0dd4-4ebe-8ec5-de2d0f41be7e",
  "orderId": "44567801-a504-4f09-8089-31ea78bc239b",
  "status": "PENDING",
  "signerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "identity": "199001011234"
  },
  "provider": "bankid",
  "language": "en",
  "redirectUrl": "https://sign.provider.com/session/abc123",
  "returnUrl": "https://yourapp.com/orders/123/complete",
  "documentUrl": "https://api.yourapp.com/documents/signed-contract-123.pdf",
  "completedAt": "2024-01-15T14:30:00Z",
  "expiresAt": "2024-01-15T23:59:59Z",
  "failureReason": "User canceled signing process",
  "createdAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "contract_type": "postpaid_subscription",
    "customer_segment": "b2b"
  }
}

CreateSigningSessionRequest

Request to create a contract signing session for an order.

orderIdstringrequired

The order that requires contract signing.

signerDetailsobject with string keysrequired

Information about the person who will sign the contract.

The specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider.

Show child attributes
*string
returnUrlstringurirequired

The URL where the user will be redirected after signing completion or failure.

providerstring

The preferred signing provider. If not specified, the default provider will be used.

languagestringdefault en

The language for the signing interface.

metadataobject with string keys

Additional metadata for the signing session.

Show child attributes
*string
CreateSigningSessionRequest
{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "signerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "identity": "199001011234"
  },
  "returnUrl": "https://yourapp.com/orders/123/complete",
  "provider": "bankid",
  "language": "sv",
  "metadata": {
    "contract_type": "postpaid_subscription",
    "customer_segment": "b2b"
  }
}

SigningRequirement

Whether a signer detail field is optional or required for a signing provider.

  • 'OPTIONAL': The field is optional and may be omitted.
  • 'REQUIRED': The field is required and must be provided.
enum<string>

values

  • OPTIONAL
  • REQUIRED
SigningRequirement
"OPTIONAL"

SigningProvider

A signing provider and its requirements for signer details.

providerstringrequired

The unique identifier for the signing provider.

namestringrequired

The display name of the signing provider.

descriptionstring

A brief description of the signing provider and its use cases.

supportedCountriesarray of string

List of country codes where this provider is available.

supportedLanguagesarray of string

List of language codes supported by this provider.

requirementsobject with string keysrequired

Information that may or must be collected from the signer before initiating the signing process.

Each key represents a field name in the signerDetails object, and the value indicates whether it's optional or required.

Show child attributes
*enum<string>

Whether a signer detail field is optional or required for a signing provider.

  • 'OPTIONAL': The field is optional and may be omitted.
  • 'REQUIRED': The field is required and must be provided.

values

  • OPTIONAL
  • REQUIRED
capabilitiesobject

Additional capabilities and features supported by this provider.

Show child attributes
multipleSignersboolean

Whether the provider supports multiple signers on the same document.

documentTemplatesboolean

Whether the provider supports custom document templates.

biometricSigningboolean

Whether the provider supports biometric signing methods.

SigningProvider
{
  "provider": "bankid",
  "name": "BankID",
  "description": "Swedish digital identity verification and signing service",
  "supportedCountries": [
    "SE"
  ],
  "supportedLanguages": [
    "sv",
    "en"
  ],
  "requirements": {
    "name": "REQUIRED",
    "email": "REQUIRED",
    "identity": "REQUIRED"
  },
  "capabilities": {
    "multipleSigners": false,
    "documentTemplates": true,
    "biometricSigning": true
  }
}

ValidateAddressRequest

Request to validate an address.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

ValidateAddressRequest
{
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

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.

validbooleanrequired

Whether the provided address is valid.

suggestedAddressobject

If provided, a suggestion for a corrected address by the underlying address validation service.

Do note that this may be returned for seemingly valid addresses, where the network has a more precise or standardized version of the address. A typical example of this is the address is found in the networks' registry but under a different name because it contains aliases or minor formatting issues, mistyped zip codes, etc.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

validationDetailsobject

Additional validation details.

Show child attributes
issuesarray of object

Specific issues found with the address.

Show child attributes
messagestringrequired

Description of the issue found.

propertystring

The property or field related to the issue (e.g., "street", "zipCode").

AddressValidationResult
{
  "valid": false,
  "suggestedAddress": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "validationDetails": {
    "issues": [
      {
        "message": "Missing city",
        "property": "city"
      },
      {
        "message": "Invalid zip format",
        "property": "zip"
      }
    ]
  }
}

CheckPortingEligibilityRequest

Request to check if a phone number is eligible for porting.

msisdnstringphonerequired

The phone number to check for porting eligibility.

CheckPortingEligibilityRequest
{
  "msisdn": "+15551234567"
}

PortingEligibilityResult

Result of number porting eligibility check.

msisdnstringphonerequired

The phone number that was checked.

eligiblebooleanrequired

Whether the number is eligible for porting.

networkProviderIdstring

The identifier for the current network provider, if detectable

ineligibilityReasonstring

Reason why number is not eligible (only present if eligible is false).

PortingEligibilityResult
{
  "msisdn": "+15551234567",
  "eligible": true,
  "networkProviderId": "tmobile-us",
  "ineligibilityReason": "Number not found or not portable"
}

GetDeviceInfoRequest

Request to get device information by IMEI.

imeistringrequired

The International Mobile Equipment Identity of the device.

GetDeviceInfoRequest
{
  "imei": "356938035643809"
}

DeviceInfo

Information about a device based on its IMEI.

imeistringrequired

The device IMEI that was checked.

tacstring

The device TAC (Type Allocation Code), which is the first 8 digits of the IMEI identifying the device model and manufacturer.

esimbooleanrequired

Whether the device supports eSIM.

manufacturerstring

Device manufacturer.

modelstring

Device model.

marketingNamestring

Device marketing name.

DeviceInfo
{
  "imei": "356938035643809",
  "tac": "35693803",
  "esim": true,
  "manufacturer": "Apple",
  "model": "A2653",
  "marketingName": "iPhone 15 Pro"
}

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.

querystringmin length 2required

Part of the device name to match, such as the brand, the model, or both.

limitinteger>= 1<= 50default 20

The largest number of devices to return.

SearchDevicesRequest
{
  "query": "iPhone 15",
  "limit": 20
}

DeviceMatch

A device the network knows by name. It carries no IMEI, because a name matches a model rather than one handset.

tacstring

The device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.

esimbooleanrequired

Whether the device supports eSIM.

manufacturerstring

Device manufacturer.

modelstring

Device model.

marketingNamestring

Device marketing name.

DeviceMatch
{
  "tac": "35693803",
  "esim": true,
  "manufacturer": "Apple",
  "model": "A2653",
  "marketingName": "iPhone 15 Pro"
}

DeviceSearchResult

The devices whose name matches the query.

itemsarray of DeviceMatchrequired

One entry per matching device. An empty list means the network knows no device by that name.

Show child attributes
tacstring

The device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.

esimbooleanrequired

Whether the device supports eSIM.

manufacturerstring

Device manufacturer.

modelstring

Device model.

marketingNamestring

Device marketing name.

DeviceSearchResult
{
  "items": [
    {
      "tac": "35693803",
      "esim": true,
      "manufacturer": "Apple",
      "model": "A2653",
      "marketingName": "iPhone 15 Pro"
    }
  ]
}

CheckNetworkCoverageRequest

Request to check network coverage for an address.

addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

CheckNetworkCoverageRequest
{
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  }
}

Coordinates

A geographic location in WGS84 coordinates, the standard used by GPS.

latitudenumberfloatrequired

Latitude in decimal degrees. Positive values are north of the equator.

longitudenumberfloatrequired

Longitude in decimal degrees. Negative values are west of the prime meridian.

Coordinates
{
  "latitude": 40.7128,
  "longitude": -74.006
}

TechnologyCoverage

Coverage details for a single network technology (such as 4G or 5G) at a checked location.

availablebooleanrequired

Whether this technology is available at the checked location.

TechnologyCoverage
{
  "available": true
}

NetworkCoverage

Network coverage information for a specific address.

What data is returned depends on the underlying network provider, so only the required fields are guaranteed to be present.

addressobjectrequired

The address that was checked.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
street1stringrequired

The first line of the address, typically street and house number.

street2string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

attentionstring

An optional line for specifying a person, department, or attention to a specific entity within an address.

coverageLevelenum<string>required

Overall network coverage quality at this location.

values

  • EXCELLENT
  • GOOD
  • FAIR
  • POOR
  • NO_COVERAGE
coordinatesobject

Resolved coordinates for the address, if available.

A geographic location in WGS84 coordinates, the standard used by GPS.

Show child attributes
latitudenumberfloatrequired

Latitude in decimal degrees. Positive values are north of the equator.

longitudenumberfloatrequired

Longitude in decimal degrees. Negative values are west of the prime meridian.

networkProviderIdstring

Which network this coverage data applies to.

coverageobject with string keys

Coverage information per technology, if available.

Show child attributes
3gobjectrequired

Coverage details for a single network technology (such as 4G or 5G) at a checked location.

Show child attributes
availablebooleanrequired

Whether this technology is available at the checked location.

4gobjectrequired

Coverage details for a single network technology (such as 4G or 5G) at a checked location.

Show child attributes
availablebooleanrequired

Whether this technology is available at the checked location.

5gobjectrequired

Coverage details for a single network technology (such as 4G or 5G) at a checked location.

Show child attributes
availablebooleanrequired

Whether this technology is available at the checked location.

*object

Coverage details for a single network technology (such as 4G or 5G) at a checked location.

Show child attributes
availablebooleanrequired

Whether this technology is available at the checked location.

roamingStatusstring

The roaming status at this location, if reported by the network provider (e.g., whether the location is served by the home network or a roaming partner).

NetworkCoverage
{
  "address": {
    "street1": "500 S Main St",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "coverageLevel": "GOOD",
  "coordinates": {
    "latitude": 40.7128,
    "longitude": -74.006
  },
  "networkProviderId": "tmobile-us",
  "coverage": {
    "3g": {
      "available": true
    },
    "4g": {
      "available": true
    },
    "5g": {
      "available": true
    },
    "propertyName": {
      "available": true
    }
  },
  "roamingStatus": "HOME"
}

NumberType

The service class of a phone number, determining what kind of subscription it can be used for.

  • CELL: Mobile number for voice, SMS, and data subscriptions
  • FIXED: Fixed-line (landline) number
  • DATA: Number for data-only subscriptions
  • M2M: Number for machine-to-machine/IoT subscriptions
enum<string>

ExampleCELL

values

  • CELL
  • FIXED
  • DATA
  • M2M
NumberType
"CELL"

LeaseNumbersRequest

Request to lease phone numbers for use in orders.

typesarray of NumberTyperequired

Types of numbers to lease.

countinteger>= 1<= 10required

Number of phone numbers to lease.

LeaseNumbersRequest
{
  "types": [
    "CELL"
  ],
  "count": 2
}

LeasedNumber

A phone number that has been leased for use in orders.

msisdnstringphonerequired

The leased phone number.

typeenum<string>required

The service class of a phone number, determining what kind of subscription it can be used for.

  • CELL: Mobile number for voice, SMS, and data subscriptions
  • FIXED: Fixed-line (landline) number
  • DATA: Number for data-only subscriptions
  • M2M: Number for machine-to-machine/IoT subscriptions

values

  • CELL
  • FIXED
  • DATA
  • M2M
gradeinteger>= 1<= 10required

Quality grade of the number (1=premium, 10=standard).

availableAtstringdate-time

When this number became available for leasing.

leasedAtstringdate-time

When this number was leased.

expiresAtstringdate-timerequired

When this lease expires if not used in an order.

metadataobject with string keys

Additional number metadata.

Show child attributes
*string
LeasedNumber
{
  "msisdn": "+15551234567",
  "type": "CELL",
  "grade": 5,
  "availableAt": "2024-01-15T10:00:00Z",
  "leasedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T11:30:00Z",
  "metadata": {
    "region": "New York",
    "areaCode": "555"
  }
}

NumberLeaseResult

Result of a number leasing request.

numbersarray of LeasedNumberrequired

The leased phone numbers.

Show child attributes
msisdnstringphonerequired

The leased phone number.

typeenum<string>required

The service class of a phone number, determining what kind of subscription it can be used for.

  • CELL: Mobile number for voice, SMS, and data subscriptions
  • FIXED: Fixed-line (landline) number
  • DATA: Number for data-only subscriptions
  • M2M: Number for machine-to-machine/IoT subscriptions

values

  • CELL
  • FIXED
  • DATA
  • M2M
gradeinteger>= 1<= 10required

Quality grade of the number (1=premium, 10=standard).

availableAtstringdate-time

When this number became available for leasing.

leasedAtstringdate-time

When this number was leased.

expiresAtstringdate-timerequired

When this lease expires if not used in an order.

metadataobject with string keys

Additional number metadata.

Show child attributes
*string
leaseTokenstringrequired

Token to use when creating subscription line items with these numbers.

Provide this token in the leaseToken field when ordering or creating a subscription along with the chosen msisdn from the leased numbers.

expiresAtstringdate-timerequired

When this lease expires if not used in an order.

NumberLeaseResult
{
  "numbers": [
    {
      "msisdn": "+15551234567",
      "type": "CELL",
      "grade": 5,
      "availableAt": "2024-01-15T10:00:00Z",
      "leasedAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-01-15T11:30:00Z",
      "metadata": {
        "region": "New York",
        "areaCode": "555"
      }
    }
  ],
  "leaseToken": "lease_abc123def456",
  "expiresAt": "2024-01-15T11:30:00Z"
}

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
enum<string>

values

  • PHYSICAL
  • ESIM
SimType
"PHYSICAL"

SimStatus

Current lifecycle status of the SIM card in inventory.

  • AVAILABLE: In stock and free to be assigned to a subscription
  • IN_USE: Currently assigned to an active subscription
  • RESERVED: Held for a pending order or activation
  • CONSUMED: Used up and no longer assignable (for example a single-use eSIM profile)
  • BRAND_RESERVED: Set aside for a specific brand and not generally assignable
enum<string>

values

  • AVAILABLE
  • IN_USE
  • RESERVED
  • CONSUMED
  • BRAND_RESERVED
SimStatus
"AVAILABLE"

EsimInstallationStatus

The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.

enum<string>

values

  • AVAILABLE
  • ALLOCATED
  • LINKED
  • CONFIRMED
  • RELEASED
  • DOWNLOADED
  • INSTALLED
  • ENABLED
  • DISABLED
  • ERROR
  • UNAVAILABLE
  • DELETED
EsimInstallationStatus
"AVAILABLE"

EsimProfile

Live eSIM profile status from the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device.

statusenum<string>required

The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.

values

  • AVAILABLE
  • ALLOCATED
  • LINKED
  • CONFIRMED
  • RELEASED
  • DOWNLOADED
  • INSTALLED
  • ENABLED
  • DISABLED
  • ERROR
  • UNAVAILABLE
  • DELETED
eidstring

The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.

lastOperationAtstringdate-time

When the last eUICC operation occurred for this profile.

EsimProfile
{
  "status": "AVAILABLE",
  "eid": "89049032004008882600009B40002780",
  "lastOperationAt": "2024-06-15T14:30:00Z"
}

InventorySim

A SIM card from inventory. For eSIM cards, the response may include live installation status from the network operator when the SIM is linked to a subscription.

iccidstringrequired

The ICCID (Integrated Circuit Card Identifier) of the SIM card.

imsistring

The IMSI (International Mobile Subscriber Identity) of the SIM.

typeenum<string>required

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

  • PHYSICAL
  • ESIM
statusenum<string>required

Current lifecycle status of the SIM card in inventory.

  • AVAILABLE: In stock and free to be assigned to a subscription
  • IN_USE: Currently assigned to an active subscription
  • RESERVED: Held for a pending order or activation
  • CONSUMED: Used up and no longer assignable (for example a single-use eSIM profile)
  • BRAND_RESERVED: Set aside for a specific brand and not generally assignable

values

  • AVAILABLE
  • IN_USE
  • RESERVED
  • CONSUMED
  • BRAND_RESERVED
lpastring

Local Profile Assistant address for eSIM activation.

esimProfileobject

Live eSIM profile status from the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device.

Show child attributes
statusenum<string>required

The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.

values

  • AVAILABLE
  • ALLOCATED
  • LINKED
  • CONFIRMED
  • RELEASED
  • DOWNLOADED
  • INSTALLED
  • ENABLED
  • DISABLED
  • ERROR
  • UNAVAILABLE
  • DELETED
eidstring

The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.

lastOperationAtstringdate-time

When the last eUICC operation occurred for this profile.

createdAtstringdate-time

When the SIM was added to inventory.

updatedAtstringdate-time

When the SIM was last updated in inventory.

InventorySim
{
  "iccid": "8946200508271016579",
  "imsi": "310150000000001",
  "type": "PHYSICAL",
  "status": "AVAILABLE",
  "lpa": "1$rsp.example.com$ABCD1234",
  "esimProfile": {
    "status": "AVAILABLE",
    "eid": "89049032004008882600009B40002780",
    "lastOperationAt": "2024-06-15T14:30:00Z"
  },
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-06-15T14:30:00Z"
}

EmbeddedWorkflowTask

Essential workflow task information for tracking webhook-triggered workflow executions.

workflowTaskIdstringrequired

The unique identifier for the workflow task.

namestringrequired

The name of the workflow that was triggered.

descriptionstring

A description of what the workflow task does.

createdAtstringdate-timerequired

When the workflow task was created.

EmbeddedWorkflowTask
{
  "workflowTaskId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Process Customer Order",
  "description": "Processes new customer orders and initiates fulfillment",
  "createdAt": "2024-01-15T10:30:00Z"
}

ReportRunStatus

The current stage of a report run in its lifecycle.

enum<string>

values

  • QUEUED
  • RUNNING
  • SUCCEEDED
  • FAILED
ReportRunStatus
"QUEUED"

ReportRun

A generated report and its current state. When the report has finished generating, a time-limited download link is provided so the file can be fetched directly.

reportRunIdstringuuidrequired

The unique identifier for this report run.

reportKeystringrequired

Identifies which report was generated.

statusenum<string>required

The current stage of a report run in its lifecycle.

values

  • QUEUED
  • RUNNING
  • SUCCEEDED
  • FAILED
downloadUrlstring | nullurirequired

A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed.

createdAtstringdate-timerequired

When the report run was requested.

completedAtstring | nulldate-timerequired

When the report run finished generating. Null while it is still in progress.

ReportRun
{
  "reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "reportKey": "subscriber_base_and_revenue",
  "status": "QUEUED",
  "downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:00Z"
}

EventEnvelope

The common wrapper around every webhook delivery. Each webhook POST body contains this envelope: a stable event identifier for deduplication, the event type to dispatch on, when the change happened, and the event-specific payload in data.

eventIdstringuuidrequired

Unique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.

typestringrequired

Event type identifier (dot namespaced, e.g. subscription.created).

occurredAtstringdate-timerequired

RFC 3339 timestamp when the underlying change occurred.

dataanyrequired

Event-specific payload; structure depends on event type.

EventEnvelope
{
  "eventId": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab",
  "type": "subscription.created",
  "occurredAt": "2024-01-15T10:30:00Z",
  "data": null
}