Get order

Authorizations

X-Api-Key

string

header

required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Path Parameters

orderId

string

required

The unique identifier of the order

Response

Order retrieved successfully

A shopping cart for telecommunications services and products. Add line items to configure services, get pricing, and submit for fulfillment. Orders track progress from creation through completion.

orderId

string

required

Unique identifier for the order.

Example:

"order-123"

state

enum<string>

required

The status of an order in its lifecycle.

PENDING: Order is in cart state, can be modified
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

Available options:

PENDING,

SUBMITTED,

PENDING_APPROVAL,

PROCESSING,

COMPLETED,

CANCELLED,

EXPIRED

customerType

enum<string>

required

The type of customer.

Available options:

CONSUMER,

BUSINESS

lineItems

required

Line items in the order.

A line item in an order representing a billable action or service.

Subscription
License
Add-on
Top-up
External Product
External Item
Subscription Change
License Change
Add-on Change

Show child attributes

lineItems.type

enum<string>

required

Line item type discriminator.

Available options:

SUBSCRIPTION

lineItems.lineItemId

string

required

Unique identifier for this line item within the order.

Example:

"line-item-1"

lineItems.productOfferingId

string

required

The product offering to create a subscription for.

Example:

"mobile-plan-basic"

lineItems.msisdn

string

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.

Example:

"+15551234567"

lineItems.leaseToken

string

Token received when leasing a number. Required when an msisdn is provided from the number pool.

lineItems.tempNumber

boolean

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

lineItems.porting

object

Details needed to port in a number for this subscription.

Show child attributes

lineItems.porting.details

USPortingDetails · object

required

description: Detailed information required for the porting process, varying by country and provider.

USPortingDetails
SwedishPortingDetails

Show child attributes

lineItems.porting.details.firstName

string

required

The first name of the person requesting the port.

lineItems.porting.details.lastName

string

required

The last name of the person requesting the port.

lineItems.porting.details.address

object

required

Show child attributes

lineItems.porting.details.address.street1

string

required

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

Example:

"500 S Main St"

lineItems.porting.details.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

lineItems.porting.details.address.zip

string

required

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

Example:

"01701"

lineItems.porting.details.address.country

string

required

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

Example:

"US"

lineItems.porting.details.address.street2

string

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

Example:

"Apt 1"

lineItems.porting.details.address.state

string

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

Example:

"CA"

lineItems.porting.details.address.region

string

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

lineItems.porting.details.address.attention

string

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

lineItems.porting.details.accountNumber

string

The account number with the current provider.

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

lineItems.porting.details.passcode

string

The passcode or pin associated with the account at the current provider.

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

lineItems.extensions

object

Additional subscription extensions fields for custom subscription types.

Show child attributes

lineItems.extensions.{key}

string

lineItems.display

string

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

lineItems.subscriber

object

Subscriber information (required eventually).

Show child attributes

lineItems.subscriber.name

string

Name of the subscriber.

Example:

"John Doe"

lineItems.subscriber.email

string<email>

Contact email of the subscriber.

Example:

"[email protected]"

lineItems.subscriber.msisdn

string<phone>

Contact phone number of the subscriber. May be the same as the subscription's msisdn.

Example:

"+15551234567"

lineItems.subscriber.address

object

The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions.

In the US, this is the E911 address.

Show child attributes

lineItems.subscriber.address.street1

string

required

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

Example:

"500 S Main St"

lineItems.subscriber.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

lineItems.subscriber.address.zip

string

required

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

Example:

"01701"

lineItems.subscriber.address.country

string

required

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

Example:

"US"

lineItems.subscriber.address.street2

string

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

Example:

"Apt 1"

lineItems.subscriber.address.state

string

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

Example:

"CA"

lineItems.subscriber.address.region

string

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

lineItems.subscriber.address.attention

string

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

lineItems.sim

object

SIM configuration (required eventually).

Show child attributes

lineItems.sim.esim

boolean

required

Whether this subscription should use eSIM technology.

Example:

true

lineItems.sim.imei

string

International Mobile Equipment Identity for eSIM activation.

Some networks require this to activate the eSIM.

Example:

"356938035643809"

lineItems.sim.iccid

string

Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card.

This feature only applies to certain networks.

Example:

"8931440400000000000"

lineItems.scheduleActivationAt

string<date>

Date when the subscription should be activated.

Example:

"2024-02-01"

lineItems.metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

lineItems.metadata.{key}

string

validation

object

required

Validation status of the order and its line items.

Show child attributes

validation.isValid

boolean

required

Whether the order is valid and ready for submission.

Example:

false

validation.missingFields

string[]

Required fields that are still missing.

Example:

["customer", "billing.address"]

validation.errors

object[]

Order-level validation errors.

Show child attributes

validation.errors.message

string

required

Validation error message.

validation.errors.property

string

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

validation.lineItemValidation

object[]

Validation status for each line item.

Show child attributes

validation.lineItemValidation.lineItemId

string

Reference to the line item.

Example:

"line-item-1"

validation.lineItemValidation.isValid

boolean

Whether this line item is valid.

Example:

false

validation.lineItemValidation.missingFields

string[]

Required fields that are still missing.

Example:

["subscriber.name", "sim.iccid"]

validation.lineItemValidation.errors

object[]

Validation errors for this line item.

Show child attributes

validation.lineItemValidation.errors.message

string

required

Validation error message.

validation.lineItemValidation.errors.property

string

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

requirements

object

required

Requirements to submit the order. All listed requirements must be met before the order can be submitted.

What is required depends on platform configuration and the contents of the order.

For example, a prepaid order with only free items would not require payment, it could however require card capture. Postpaid orders typically either require card capture or signing.

Show child attributes

requirements.requiresPayment

enum<string>

Whether this order requires payment before submission. If required, a paymentSessionId must be provided when submitting the order.

Available options:

NOT_REQUIRED,

OPTIONAL,

REQUIRED

requirements.requiresPaymentProfile

enum<string>

Whether this order requires saving a payment profile for future billing. If required, a paymentProfileSessionId must be provided when submitting the order.

Available options:

NOT_REQUIRED,

OPTIONAL,

REQUIRED

requirements.requiresSigning

enum<string>

Whether this order requires digital signing. If required, a signingSessionId must be provided when submitting the order.

Available options:

NOT_REQUIRED,

OPTIONAL,

REQUIRED

createdAt

string<date-time>

required

When the order was created.

Example:

"2024-01-15T10:00:00Z"

updatedAt

string<date-time>

required

When the order was last updated.

Example:

"2024-01-15T10:30:00Z"

user

object

The user associated with this order. Includes minimal details about the user and creation details if the user was created during order fulfillment.

Show child attributes

user.userId

string

required

The user ID (existing or newly created).

Example:

"c47ac10b-58cc-4372-a567-0e02b2c3d479"

user.newUser

boolean

required

Indicates if the user was/will be created as part of order fulfillment.

Example:

true

user.name

string

User full name, only returned for new users.

Example:

"John Doe"

customerId

string

The customer ID (existing or newly created).

Example:

"b47ac10b-58cc-4372-a567-0e02b2c3d479"

customer

object

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

customer.customerType

enum<string>

required

The type of customer.

Available options:

CONSUMER,

BUSINESS

customer.name

string

required

Customer name.

Example:

"John Doe"

customer.newCustomer

boolean

required

Indicates if the customer was/will be created as part of order fulfillment.

Example:

true

customer.customerId

string

The customer ID (existing or newly created when created).

Example:

"b47ac10b-58cc-4372-a567-0e02b2c3d479"

billing

object

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

billing.name

string

Billing contact name.

Example:

"John Doe"

billing.email

string<email>

Billing contact email.

Example:

"[email protected]"

billing.address

object

Show child attributes

billing.address.street1

string

required

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

Example:

"500 S Main St"

billing.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

billing.address.zip

string

required

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

Example:

"01701"

billing.address.country

string

required

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

Example:

"US"

billing.address.street2

string

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

Example:

"Apt 1"

billing.address.state

string

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

Example:

"CA"

billing.address.region

string

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

billing.address.attention

string

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

shipping

object

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

Show child attributes

shipping.name

string

required

Name of the shipping recipient.

Example:

"John Doe"

shipping.address

object

required

Show child attributes

shipping.address.street1

string

required

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

Example:

"500 S Main St"

shipping.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

shipping.address.zip

string

required

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

Example:

"01701"

shipping.address.country

string

required

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

Example:

"US"

shipping.address.street2

string

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

Example:

"Apt 1"

shipping.address.state

string

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

Example:

"CA"

shipping.address.region

string

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

shipping.address.attention

string

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

shipping.msisdn

string<phone>

Phone number for delivery contact.

Example:

"+15551234567"

shipping.instructions

string

Special delivery instructions.

Example:

"Leave at front door"

Promotional code applied to this order, if any.

Example:

"STUDENT2024"

consents

object

Customer consents and acknowledgments.

Show child attributes

consents.{key}

string

Example:

{
  "termsOfService": "true",
  "marketing": "true"
}

pricing

object

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.

Show child attributes

pricing.total

number<decimal>

required

Total amount due for the order.

Example:

137.39

pricing.currency

string

required

Currency for all pricing amounts.

Example:

"USD"

pricing.calculatedAt

string<date-time>

required

When the pricing was last calculated.

Example:

"2024-01-15T10:30:00Z"

pricing.subtotal

number<decimal>

Subtotal before taxes and fees.

Example:

125.99

pricing.taxAmount

number<decimal>

Tax amount for the order. Set to 0 for orders that will be invoiced separately.

Example:

10.08

pricing.fees

number<decimal>

Setup fees, activation fees, processing fees, etc.

Example:

1.32

pricing.taxIncluded

boolean

Whether taxes are included in the total.

Example:

true

pricing.recurringCosts

object

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

Show child attributes

pricing.recurringCosts.subtotal

number<decimal>

Recurring subtotal before taxes.

Example:

29.99

pricing.recurringCosts.total

number<decimal>

Total estimated recurring amount.

Example:

32.39

pricing.recurringCosts.taxAmount

number<decimal>

Estimated tax on recurring charges.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

Example:

2.4

pricing.recurringCosts.taxIncluded

boolean

Whether taxes are included in the total.

Example:

true

pricing.recurringCosts.billingCycle

object

The billing cycle for recurring prices.

Show child attributes

pricing.recurringCosts.billingCycle.period

enum<string>

The billing period.

Available options:

MONTHLY

pricing.recurringCosts.billingCycle.interval

integer

The interval of the billing period.

Example:

1

pricing.initialInvoice

object

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes

pricing.initialInvoice.subtotal

number<decimal>

First invoice subtotal (e.g., prorated amount, setup fees).

Example:

14.5

pricing.initialInvoice.total

number<decimal>

Total first invoice amount.

Example:

15.66

pricing.initialInvoice.taxAmount

number<decimal>

Estimated tax on initial invoice charges.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

pricing.initialInvoice.taxIncluded

boolean

Whether taxes are included in the total.

Example:

true

pricing.initialInvoice.period

object

Period covered by the initial invoice.

Show child attributes

pricing.initialInvoice.period.start

string<date>

Start date of the initial billing period.

Example:

"2024-01-15"

pricing.initialInvoice.period.end

string<date>

End date of the initial billing period.

Example:

"2024-01-31"

pricing.lineItemPricing

object[]

Per-line-item pricing breakdown.

Show child attributes

pricing.lineItemPricing.lineItemId

string

required

Reference to the line item.

Example:

"e47ac10b-58cc-4372-a567-0e02b2c3d479"

pricing.lineItemPricing.amount

number<decimal>

required

Cost for this line item in the order.

Example:

999

pricing.lineItemPricing.recurringAmount

number<decimal>

required

Recurring cost for this line item.

Example:

29.99

pricing.lineItemPricing.description

string

Description of what this line item covers.

Example:

"iPhone 15 Pro + Premium Plan"

pricing.lineItemPricing.taxAmount

number<decimal>

Tax amount for this line item.

Example:

79.92

pricing.lineItemPricing.taxIncluded

boolean

Whether taxes are included in the amount.

Example:

true

pricing.lineItemPricing.taxBreakdown

object[]

Tax breakdown for this line item.

Show child attributes

pricing.lineItemPricing.taxBreakdown.description

string

required

Description of this tax component.

Example:

"Sales Tax"

pricing.lineItemPricing.taxBreakdown.amount

number<decimal>

required

Tax amount for this component.

Example:

2.4

pricing.lineItemPricing.taxBreakdown.rate

number<decimal>

Tax rate as a percentage (optional).

Example:

8.25

pricing.lineItemPricing.initialInvoiceAmount

number<decimal>

Amount for this line item on the first invoice.

Example:

14.5

expiresAt

string<date-time>

When the order expires if not submitted (automatically refreshed on each order update to maintain active session).

Example:

"2024-01-22T10:30:00Z"

submittedAt

string<date-time>

When the order was submitted for fulfillment.

Example:

"2024-01-15T14:30:00Z"

completedAt

string<date-time>

When the order was completed.

Example:

"2024-01-15T15:00:00Z"

createdEntities

object

Entities created as part of order fulfillment.

Show child attributes

createdEntities.subscriptions

object[]

Subscriptions created during order fulfillment.

Show child attributes

createdEntities.subscriptions.subscriptionId

string

required

The unique identifier for the subscription.

createdEntities.subscriptions.status

enum<string>

required

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED

createdEntities.subscriptions.type

string

required

The type of subscription, categorizing the service into various telecommunications service types.

createdEntities.subscriptions.display

string

required

The display name for the subscription, typically a pretty-print of the msisdn.

createdEntities.subscriptions.msisdn

string

required

The currently active phone number for this subscription.

createdEntities.subscriptions.customerId

string

required

The unique identifier for the customer who owns this subscription.

createdEntities.subscriptions.productOfferingId

string

required

The unique identifier for the product offering associated with this subscription.

createdEntities.subscriptions.subscriberId

string

required

The unique identifier for the subscriber associated with this subscription.

createdEntities.subscriptions.activatedAt

string<date-time>

required

The date and time when the subscription was activated.

createdEntities.subscriptions.createdAt

string<date-time>

required

The date and time when the subscription was created.

createdEntities.subscriptions.updatedAt

string<date-time>

required

The date and time when the subscription was last updated.

createdEntities.subscriptions.createdByLineItem

string

required

Line item ID that created this subscription.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

createdEntities.subscriptions.cancelledAt

string<date-time>

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

createdEntities.licenses

object[]

Licenses created during order fulfillment.

Show child attributes

createdEntities.licenses.licenseId

string

required

The unique identifier for the license.

createdEntities.licenses.status

enum<string>

required

The status of the license.

Available options:

PENDING,

ACTIVE,

PAUSED,

CANCELLED,

BLOCKED

createdEntities.licenses.type

string

required

The type of license, categorizing the software product or service into various telecommunications license types.

createdEntities.licenses.customerId

string

required

The unique identifier for the customer who owns this license.

createdEntities.licenses.productOfferingId

string

required

The unique identifier for the product offering associated with this license.

createdEntities.licenses.activatedAt

string<date-time>

required

The date when the license was activated.

createdEntities.licenses.createdByLineItem

string

required

Line item ID that created this license.

Example:

"g47ac10b-58cc-4372-a567-0e02b2c3d479"

createdEntities.licenses.assignedTo

Subscription · object

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

createdEntities.licenses.assignedTo.type

enum<string>

required

Available options:

SUBSCRIPTION

createdEntities.licenses.assignedTo.subscriptionId

string

required

createdEntities.licenses.cancelledAt

string<date-time>

The date when the license was cancelled (if applicable).

createdEntities.licenses.pausedAt

string<date>

The date when the license was paused (if applicable).

createdEntities.addons

object[]

Add-ons created during order fulfillment.

Show child attributes

createdEntities.addons.status

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

Available options:

PENDING,

ACTIVE,

CANCELLED

createdEntities.addons.createdByLineItem

string

required

Line item ID that created this add-on.

Example:

"h47ac10b-58cc-4372-a567-0e02b2c3d479"

createdEntities.addons.productOfferingId

string

The unique identifier for the product offering.

createdEntities.addons.productOfferingGroupId

string

The unique identifier for the product offering group.

createdEntities.addons.licenseId

string

The unique identifier of the license associated with this add-on (if applicable).

createdEntities.addons.addedAt

string<date-time>

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

createdEntities.addons.updatedAt

string<date-time>

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

createdEntities.addons.cancelledAt

string<date-time>

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

createdEntities.addons.metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

createdEntities.addons.metadata.{key}

string

createdEntities.modifications

object[]

Modifications applied during order fulfillment.

Show child attributes

createdEntities.modifications.type

enum<string>

required

Type of modification applied.

Available options:

SUBSCRIPTION_CHANGE,

LICENSE_CHANGE,

ADDON_CHANGE

createdEntities.modifications.targetId

string

required

ID of the entity that was modified.

Example:

"e8174435-6378-4be5-a9f5-8b4aaadae5d4"

createdEntities.modifications.createdByLineItem

string

required

Line item ID that created this modification.

Example:

"i47ac10b-58cc-4372-a567-0e02b2c3d479"

createdEntities.modifications.newProductOfferingId

string

New product offering ID (for changes).

Example:

"po_mobile_premium_plus"

createdEntities.modifications.appliedAt

string<date-time>

When the modification was applied.

metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

metadata.{key}

string

Getting started

Overview

API reference

Authorizations

Path Parameters

Response