telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Orders

Manage orders and line items.

Create order

POST/orders

Create a new order with initial configuration. Orders can be created with minimal information and progressively configured.

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyCreateOrderRequestrequiredapplication/json

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.

addressobjectdeprecated

Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in customer instead.

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

Show child attributes
metadataobject with string 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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 internalCode 4119 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

Responses

201

Order created successfully

application/json

Order created successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders
curl https://apiv2.example.com/api/v2/orders \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "customerType": "BUSINESS",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    }
  },
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  ],
  "promoCode": "SUMMER2023",
  "metadata": {
    "source": "partner-storefront"
  }
}'
fetch('https://apiv2.example.com/api/v2/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerType: 'BUSINESS',
    customer: {
      customerId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479'
    },
    billing: {
      name: 'John Doe',
      email: 'billing@acme.com',
      address: {
        street: '123 Main Street',
        city: 'New York',
        zip: '10001',
        state: 'NY',
        country: 'US'
      }
    },
    lineItems: [
      {
        type: 'SUBSCRIPTION',
        lineItemId: 'line-item-1',
        productOfferingId: 'mobile-plan-basic',
        sim: {
          esim: true
        },
        subscriber: {
          name: 'John Doe',
          email: 'john.doe@example.com'
        }
      }
    ],
    promoCode: 'SUMMER2023',
    metadata: {
      source: 'partner-storefront'
    }
  })
})
requests.post("https://apiv2.example.com/api/v2/orders",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "customerType": "BUSINESS",
      "customer": {
        "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "billing": {
        "name": "John Doe",
        "email": "billing@acme.com",
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "zip": "10001",
          "state": "NY",
          "country": "US"
        }
      },
      "lineItems": [
        {
          "type": "SUBSCRIPTION",
          "lineItemId": "line-item-1",
          "productOfferingId": "mobile-plan-basic",
          "sim": {
            "esim": True
          },
          "subscriber": {
            "name": "John Doe",
            "email": "john.doe@example.com"
          }
        }
      ],
      "promoCode": "SUMMER2023",
      "metadata": {
        "source": "partner-storefront"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders"

	payload := strings.NewReader(`{
  "customerType": "BUSINESS",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    }
  },
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  ],
  "promoCode": "SUMMER2023",
  "metadata": {
    "source": "partner-storefront"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "state": "PENDING",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "BUSINESS",
    "name": "Acme Corporation",
    "newCustomer": false
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    }
  },
  "promoCode": "SUMMER2023",
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "status": "PENDING"
    }
  ],
  "pricing": {
    "subtotalMinor": 2999,
    "taxAmountMinor": 0,
    "totalMinor": 2999,
    "taxIncluded": false,
    "currency": "USD",
    "calculatedAt": "2024-01-15T10:00:00Z"
  },
  "validation": {
    "isValid": false,
    "lineItemValidation": [
      {
        "lineItemId": "line-item-1",
        "isValid": false,
        "missingFields": [
          "subscriber.address"
        ]
      }
    ]
  },
  "requirements": {
    "requiresPayment": "REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "expiresAt": "2024-01-22T10:00:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "source": "partner-storefront"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

List orders

GET/orders

List orders with optional filtering and pagination.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

stateenum<string>

Filter by order state

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
userIdstring

Filter by user ID

customerIdstring

Filter by customer. 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.

expiresAfterstringdate-time

Filter orders expiring after this date

expiresBeforestringdate-time

Filter orders expiring before this date

Responses

200

Orders retrieved successfully

application/json

Orders retrieved successfully

object

itemsarray of OrderListItemrequired
Show child attributes
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
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.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

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

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /orders
curl https://apiv2.example.com/api/v2/orders \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/orders', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get("https://apiv2.example.com/api/v2/orders",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "orderId": "ce0539b4-ec57-4709-b72e-47892586d05a",
      "state": "PENDING",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "pricing": {
        "totalMinor": 13739,
        "currency": "USD"
      },
      "validationStatus": "VALID",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-01-22T10:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get order

GET/orders/{orderId}

Retrieve a specific order by ID with all line items and current status.

Path parameters

orderIdstringrequired

The unique identifier of the order

Responses

200

Order retrieved successfully

application/json

Order retrieved successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /orders/{orderId}
curl https://apiv2.example.com/api/v2/orders/ORDER_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "state": "PENDING",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "BUSINESS",
    "name": "Acme Corporation",
    "newCustomer": false
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    }
  },
  "promoCode": "SUMMER2023",
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "zip": "10001",
          "state": "NY",
          "country": "US"
        }
      },
      "status": "PENDING"
    }
  ],
  "pricing": {
    "subtotalMinor": 2999,
    "taxAmountMinor": 240,
    "totalMinor": 3239,
    "taxIncluded": false,
    "currency": "USD",
    "calculatedAt": "2024-01-15T10:30:00Z"
  },
  "validation": {
    "isValid": true
  },
  "requirements": {
    "requiresPayment": "REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "source": "partner-storefront"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Update order

PUT/orders/{orderId}

Update order details (excluding line items). Order must be in PENDING status.

Path parameters

orderIdstringrequired

The unique identifier of the order

BodyUpdateOrderRequestrequiredapplication/json

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.

addressobjectdeprecated

Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in customer instead.

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

Show child attributes
metadataobject with string 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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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 internalCode 4119 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

Responses

200

Order updated successfully

application/json

Order updated successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

PUT /orders/{orderId}
curl https://apiv2.example.com/api/v2/orders/ORDER_ID \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "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"
  }
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user: {
      userId: 'd47ac10b-58cc-4372-a567-0e02b2c3d479'
    },
    customer: {
      customerId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479'
    },
    billing: {
      name: 'John Doe',
      email: 'billing@example.com',
      address: {
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        city: 'Natick',
        zip: '01701',
        country: 'US',
        state: 'CA',
        region: 'Ontario',
        attention: 'John Doe'
      }
    },
    shipping: {
      name: 'John Doe',
      msisdn: '+15551234567',
      address: {
        street: '500 S Main St',
        street1: 'string',
        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'
    }
  })
})
requests.put(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "user": {
        "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "customer": {
        "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "billing": {
        "name": "John Doe",
        "email": "billing@example.com",
        "address": {
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "state": "CA",
          "region": "Ontario",
          "attention": "John Doe"
        }
      },
      "shipping": {
        "name": "John Doe",
        "msisdn": "+15551234567",
        "address": {
          "street": "500 S Main St",
          "street1": "string",
          "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"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID"

	payload := strings.NewReader(`{
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "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"
  }
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "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": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "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": {
            "street": "500 S Main St",
            "street1": "string",
            "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
    "subtotalMinor": 12599,
    "taxAmountMinor": 1008,
    "totalMinor": 13739,
    "amountDueNowMinor": 13739,
    "taxIncluded": true,
    "currency": "USD",
    "recurringCosts": {
      "subtotalMinor": 2999,
      "totalMinor": 3239,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "initialInvoice": {
      "subtotalMinor": 1450,
      "totalMinor": 1566,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "period": {
        "start": "2024-01-15",
        "end": "2024-01-31"
      }
    },
    "calculatedAt": "2024-01-15T10:30:00Z",
    "lineItems": [
      {
        "lineItemId": "line-item-1",
        "subtotalMinor": 2999,
        "totalMinor": 2747,
        "taxBreakdown": [
          {
            "description": "Sales Tax",
            "amountMinor": 240,
            "rate": 8.25
          }
        ],
        "taxAmountMinor": 247,
        "taxIncluded": true,
        "discounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "recurringDiscounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "totalDiscountsMinor": 2999,
        "description": "Premium Plan",
        "recurringAmountMinor": 2999,
        "chargedMonthAmountMinor": 14458,
        "chargedMonths": 6,
        "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"
      }
    ],
    "licenses": [
      {
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "status": "PENDING",
        "type": "PBX_USER_LEVEL",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "activatedAt": "2024-01-15",
        "cancelledAt": "2024-06-30",
        "createdByLineItem": "j47ac10b-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"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Add line item

POST/orders/{orderId}/line-items

Add a new line item to an order. Order must be in PENDING status.

Path parameters

orderIdstringrequired

The unique identifier of the order

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyAddLineItemRequestrequiredapplication/json

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

Responses

201

Line item added successfully

application/json

Line item added successfully

one ofOrderLineItem

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
esimbooleanrequired

Whether this line item uses 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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
productOfferingIdstringrequired

The plan offering to change to. The platform refuses an offering in the SIM card category.

simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
productOfferingIdstringrequired

The SIM card offering to change to. The offering must be in the SIM card category.

simobject

The SIM card of the change.

The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect.

The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
productOfferingIdstringrequired

The add-on offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/{orderId}/line-items
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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"
    }
  }
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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: {
            street: '500 S Main St',
            street1: 'string',
            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: {
          street: '500 S Main St',
          street1: 'string',
          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'
      }
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "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": {
              "street": "500 S Main St",
              "street1": "string",
              "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": {
            "street": "500 S Main St",
            "street1": "string",
            "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"
        }
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items"

	payload := strings.NewReader(`{
  "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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"
    }
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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": {
      "street": "500 S Main St",
      "street1": "string",
      "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"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Update line item

PUT/orders/{orderId}/line-items/{lineItemId}

Update a line item configuration. Order must be in PENDING status.

Path parameters

orderIdstringrequired

The unique identifier of the order

lineItemIdstringrequired

The unique identifier of the line item

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyUpdateLineItemRequestrequiredapplication/json

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

Responses

200

Line item updated successfully

application/json

Line item updated successfully

one ofOrderLineItem

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
esimbooleanrequired

Whether this line item uses 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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
productOfferingIdstringrequired

The plan offering to change to. The platform refuses an offering in the SIM card category.

simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
productOfferingIdstringrequired

The SIM card offering to change to. The offering must be in the SIM card category.

simobject

The SIM card of the change.

The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect.

The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
productOfferingIdstringrequired

The add-on offering to change to.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

PUT /orders/{orderId}/line-items/{lineItemId}
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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"
    }
  }
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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: {
            street: '500 S Main St',
            street1: 'string',
            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: {
          street: '500 S Main St',
          street1: 'string',
          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'
      }
    }
  })
})
requests.put(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "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": {
              "street": "500 S Main St",
              "street1": "string",
              "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": {
            "street": "500 S Main St",
            "street1": "string",
            "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"
        }
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID"

	payload := strings.NewReader(`{
  "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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"
    }
  }
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "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": {
        "street": "500 S Main St",
        "street1": "string",
        "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": {
      "street": "500 S Main St",
      "street1": "string",
      "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"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Remove line item

DELETE/orders/{orderId}/line-items/{lineItemId}

Remove a line item from an order. Order must be in PENDING status.

Path parameters

orderIdstringrequired

The unique identifier of the order

lineItemIdstringrequired

The unique identifier of the line item

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Responses

204

Line item removed successfully

Line item removed successfully

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

DELETE /orders/{orderId}/line-items/{lineItemId}
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.delete(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID"

	req, _ := http.NewRequest("DELETE", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Submit order

POST/orders/{orderId}/submit

Submit an order for fulfillment. Requires payment, signing, or card capture, depending on the setup. Only orders in the PENDING state can be submitted. An order paying through a payment session or payment link is in PENDING_PAYMENT and is submitted automatically once the payment succeeds — poll the order or subscribe to the order.statusChanged webhook instead of calling this endpoint.

Path parameters

orderIdstringrequired

The unique identifier of the order

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodySubmitOrderRequestrequiredapplication/json

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

Responses

200

Order submitted successfully

application/json

Order submitted successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/{orderId}/submit
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/submit \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/submit', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentSessionId: 'd2e3f4a5-b6c7-8901-2345-012345678901'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/submit",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/submit"

	payload := strings.NewReader(`{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "state": "PROCESSING",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "BUSINESS",
    "name": "Acme Corporation",
    "newCustomer": false
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    }
  },
  "promoCode": "SUMMER2023",
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "zip": "10001",
          "state": "NY",
          "country": "US"
        }
      },
      "status": "RUNNING"
    }
  ],
  "pricing": {
    "subtotalMinor": 2999,
    "taxAmountMinor": 240,
    "totalMinor": 3239,
    "taxIncluded": false,
    "currency": "USD",
    "calculatedAt": "2024-01-15T10:30:00Z"
  },
  "validation": {
    "isValid": true
  },
  "requirements": {
    "requiresPayment": "REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "submittedAt": "2024-01-15T14:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z",
  "metadata": {
    "source": "partner-storefront"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Cancel order

POST/orders/{orderId}/cancel

Cancel an order before it has been submitted. Only orders in PENDING status can be canceled. This prevents the order from being submitted and cleans up any reserved resources.

Path parameters

orderIdstringrequired

The unique identifier of the order

Bodyapplication/json

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

Responses

200

Order canceled successfully

application/json

Order canceled successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/{orderId}/cancel
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "propertyName": "string"
  }
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      propertyName: 'string'
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "metadata": {
        "propertyName": "string"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel"

	payload := strings.NewReader(`{
  "metadata": {
    "propertyName": "string"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "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": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "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": {
            "street": "500 S Main St",
            "street1": "string",
            "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
    "subtotalMinor": 12599,
    "taxAmountMinor": 1008,
    "totalMinor": 13739,
    "amountDueNowMinor": 13739,
    "taxIncluded": true,
    "currency": "USD",
    "recurringCosts": {
      "subtotalMinor": 2999,
      "totalMinor": 3239,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "initialInvoice": {
      "subtotalMinor": 1450,
      "totalMinor": 1566,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "period": {
        "start": "2024-01-15",
        "end": "2024-01-31"
      }
    },
    "calculatedAt": "2024-01-15T10:30:00Z",
    "lineItems": [
      {
        "lineItemId": "line-item-1",
        "subtotalMinor": 2999,
        "totalMinor": 2747,
        "taxBreakdown": [
          {
            "description": "Sales Tax",
            "amountMinor": 240,
            "rate": 8.25
          }
        ],
        "taxAmountMinor": 247,
        "taxIncluded": true,
        "discounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "recurringDiscounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "totalDiscountsMinor": 2999,
        "description": "Premium Plan",
        "recurringAmountMinor": 2999,
        "chargedMonthAmountMinor": 14458,
        "chargedMonths": 6,
        "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"
      }
    ],
    "licenses": [
      {
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "status": "PENDING",
        "type": "PBX_USER_LEVEL",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "activatedAt": "2024-01-15",
        "cancelledAt": "2024-06-30",
        "createdByLineItem": "j47ac10b-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"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

Approve order

POST/orders/{orderId}/approve

Approve an order that requires admin or manager approval. Only orders in PENDING_APPROVAL status can be approved. The approving user must have the appropriate role for the approval type required by the order.

Path parameters

orderIdstringrequired

The unique identifier of the order

BodyApproveOrderRequestapplication/json

Approve an order that requires admin or manager approval before fulfillment can proceed.

commentstringmax length 1000

Optional comment explaining the approval decision.

Responses

200

Order approved successfully

application/json

Order approved successfully

objectOrder

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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
streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes
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.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this 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
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 change to 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 that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

  • PLAN_CHANGE
  • SIM_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes
simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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 change to 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.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

  • PLAN_CHANGE
planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes
scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

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

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

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
subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

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
subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

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.

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.

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
taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxIncludedboolean

Whether taxes are included in the total.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes
recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes
totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

descriptionstring

Description of what this line item covers.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

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.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

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

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

createdByLineItemstringrequired

Line item ID that created this license.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/{orderId}/approve
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/approve \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "comment": "Approved after reviewing customer credit check"
}'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/approve', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    comment: 'Approved after reviewing customer credit check'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/approve",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "comment": "Approved after reviewing customer credit check"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/approve"

	payload := strings.NewReader(`{
  "comment": "Approved after reviewing customer credit check"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "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": {
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "Ontario",
      "attention": "John Doe"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street": "500 S Main St",
      "street1": "string",
      "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": {
            "street": "500 S Main St",
            "street1": "string",
            "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": {
          "street": "500 S Main St",
          "street1": "string",
          "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": {
    "subtotalMinor": 12599,
    "taxAmountMinor": 1008,
    "totalMinor": 13739,
    "amountDueNowMinor": 13739,
    "taxIncluded": true,
    "currency": "USD",
    "recurringCosts": {
      "subtotalMinor": 2999,
      "totalMinor": 3239,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "initialInvoice": {
      "subtotalMinor": 1450,
      "totalMinor": 1566,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "period": {
        "start": "2024-01-15",
        "end": "2024-01-31"
      }
    },
    "calculatedAt": "2024-01-15T10:30:00Z",
    "lineItems": [
      {
        "lineItemId": "line-item-1",
        "subtotalMinor": 2999,
        "totalMinor": 2747,
        "taxBreakdown": [
          {
            "description": "Sales Tax",
            "amountMinor": 240,
            "rate": 8.25
          }
        ],
        "taxAmountMinor": 247,
        "taxIncluded": true,
        "discounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "recurringDiscounts": [
          {
            "name": "First month free",
            "amountMinor": 2999,
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "totalDiscountsMinor": 2999,
        "description": "Premium Plan",
        "recurringAmountMinor": 2999,
        "chargedMonthAmountMinor": 14458,
        "chargedMonths": 6,
        "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"
      }
    ],
    "licenses": [
      {
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "status": "PENDING",
        "type": "PBX_USER_LEVEL",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "activatedAt": "2024-01-15",
        "cancelledAt": "2024-06-30",
        "createdByLineItem": "j47ac10b-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"
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Create order handoff token

POST/orders/{orderId}/handoff-token

Mint a short-lived token that lets a checkout pick up this draft order, so an order built over the API can be configured further and paid by the customer in a storefront checkout.

The order must still be open (PENDING or PENDING_PAYMENT). The token expires on its own, and it stops working as soon as the order is no longer open. Anyone holding the token can view and complete the order, so pass it only to the person the order is for.

Path parameters

orderIdstringrequired

The unique identifier of the order

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Responses

201

Handoff token created

application/json

Handoff token created

objectOrderHandoffToken

A short-lived token that lets a checkout pick up a draft order that was built elsewhere, for example by a support agent or a chat assistant. Anyone holding the token can view and complete the order, so pass it only to the person the order is for.

handoffTokenstringrequired

The raw handoff token. It is only returned here and cannot be retrieved again; mint a new one if it is lost.

orderIdstringrequired

The order this token hands off.

expiresAtstringdate-timerequired

When the token stops being claimable. The order itself also expires on its own schedule.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/{orderId}/handoff-token
curl https://apiv2.example.com/api/v2/orders/ORDER_ID/handoff-token \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/orders/ORDER_ID/handoff-token', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/ORDER_ID/handoff-token",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/ORDER_ID/handoff-token"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479",
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "expiresAt": "2024-01-15T11:00:00Z"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Claim order handoff

POST/orders/claim-handoff

Resolve a handoff token to the order it hands off. A checkout calls this with the token it received and then continues the order under its own session.

Fails when the token is unknown or expired, or when the order is no longer open.

Bodyrequiredapplication/json

handoffTokenstringrequired

The handoff token to resolve.

Responses

200

The order the token hands off

application/json

The order the token hands off

objectOrderHandoffClaim

The order a handoff token resolves to.

orderIdstringrequired

The order the token hands off.

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
400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

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.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /orders/claim-handoff
curl https://apiv2.example.com/api/v2/orders/claim-handoff \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
}'
fetch('https://apiv2.example.com/api/v2/orders/claim-handoff', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    handoffToken: 'oht_f47ac10b58cc4372a5670e02b2c3d479'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/orders/claim-handoff",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/orders/claim-handoff"

	payload := strings.NewReader(`{
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "customerType": "CONSUMER"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}