Skip to main content
POST
/
orders
{
  "orderId": "order-123",
  "status": "PENDING",
  "user": {
    "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "John Doe",
    "newUser": true
  },
  "customer": {
    "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "CONSUMER",
    "name": "John Doe",
    "newCustomer": true
  },
  "billing": {
    "name": "John Doe",
    "email": "billing@example.com",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    }
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "street1": "500 S Main St",
      "street2": "Apt 1",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    },
    "instructions": "Leave at front door"
  },
  "promoCode": "STUDENT2024",
  "consents": {
    "termsOfService": "true",
    "marketing": "true"
  },
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "msisdn": "+15551234567",
      "leaseToken": "<string>",
      "tempNumber": true,
      "porting": {
        "details": {
          "accountNumber": "<string>",
          "passcode": "<string>",
          "firstName": "<string>",
          "lastName": "<string>",
          "address": {
            "street1": "500 S Main St",
            "street2": "Apt 1",
            "city": "Natick",
            "zip": "01701",
            "country": "US",
            "state": "CA",
            "region": "<string>",
            "attention": "<string>"
          }
        }
      },
      "extensions": {},
      "display": "<string>",
      "subscriber": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "identity": "<string>"
      },
      "sim": {
        "esim": true,
        "imei": "356938035643809",
        "iccid": "8931440400000000000"
      },
      "scheduleActivationAt": "2024-02-01",
      "metadata": {}
    }
  ],
  "pricing": {
    "subtotal": 125.99,
    "taxAmount": 10.08,
    "fees": 1.32,
    "total": 137.39,
    "taxIncluded": true,
    "currency": "USD",
    "recurringCosts": {
      "subtotal": 29.99,
      "total": 32.39,
      "taxAmount": 2.4,
      "taxIncluded": true,
      "billingCycle": {
        "period": "MONTHLY",
        "interval": 1
      }
    },
    "initialInvoice": {
      "subtotal": 14.5,
      "total": 15.66,
      "taxAmount": 123,
      "taxIncluded": true,
      "period": {
        "start": "2024-01-15",
        "end": "2024-01-31"
      }
    },
    "lineItemPricing": [
      {
        "lineItemId": "e47ac10b-58cc-4372-a567-0e02b2c3d479",
        "description": "iPhone 15 Pro + Premium Plan",
        "amount": 999,
        "taxAmount": 79.92,
        "taxIncluded": true,
        "taxBreakdown": [
          {
            "description": "Sales Tax",
            "amount": 2.4,
            "rate": 8.25
          }
        ],
        "recurringAmount": 29.99,
        "initialInvoiceAmount": 14.5
      }
    ],
    "calculatedAt": "2024-01-15T10:30:00Z"
  },
  "validation": {
    "isValid": false,
    "missingFields": [
      "customer",
      "billing.address"
    ],
    "errors": [
      {
        "message": "<string>",
        "property": "<string>"
      }
    ],
    "lineItemValidation": [
      {
        "lineItemId": "line-item-1",
        "isValid": false,
        "missingFields": [
          "subscriber.name",
          "sim.iccid"
        ],
        "errors": [
          {
            "message": "<string>",
            "property": "<string>"
          }
        ]
      }
    ]
  },
  "requirements": {
    "requiresPayment": "NOT_REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "submittedAt": "2024-01-15T14:30:00Z",
  "completedAt": "2024-01-15T15:00:00Z",
  "createdEntities": {
    "subscriptions": [
      {
        "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
        "status": "PENDING",
        "display": "+1 (555) 123-4567",
        "msisdn": "+15551234567",
        "productOfferingId": "<string>",
        "productOffering": {
          "productOfferingId": "<string>",
          "name": "<string>",
          "price": {
            "grossPrice": 10,
            "discount": 123,
            "netPrice": 5,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "boundMonths": 12,
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "taxIncluded": true
          },
          "productOfferingGroupId": "<string>",
          "group": {
            "productOfferingGroupId": "<string>",
            "name": "<string>",
            "category": "SUBSCRIPTION_CELL"
          }
        },
        "customerId": "<string>",
        "customer": {
          "customerId": "<string>",
          "name": "<string>"
        },
        "subscriberId": "<string>",
        "subscriber": {
          "subscriberId": "<string>",
          "name": "<string>",
          "email": "jsmith@example.com",
          "address": {
            "street1": "500 S Main St",
            "street2": "Apt 1",
            "city": "Natick",
            "zip": "01701",
            "country": "US",
            "state": "CA",
            "region": "<string>",
            "attention": "<string>"
          },
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        },
        "activatedAt": "2024-01-15T10:30:00Z",
        "createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "licenses": [
      {
        "licenseId": "b3c4d5e6-f7a8-9012-3456-789012345678",
        "status": "PENDING",
        "type": "<string>",
        "productOfferingId": "<string>",
        "productOffering": {
          "productOfferingId": "<string>",
          "name": "<string>",
          "price": {
            "grossPrice": 10,
            "discount": 123,
            "netPrice": 5,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "boundMonths": 12,
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "taxIncluded": true
          },
          "productOfferingGroupId": "<string>",
          "group": {
            "productOfferingGroupId": "<string>",
            "name": "<string>",
            "category": "SUBSCRIPTION_CELL"
          }
        },
        "assignedTo": {
          "type": "SUBSCRIPTION",
          "subscriptionId": "<string>",
          "subscriptionDisplay": "<string>"
        },
        "customerId": "<string>",
        "customer": {
          "customerId": "<string>",
          "name": "<string>"
        },
        "activatedAt": "2024-01-15T10:30:00Z",
        "createdByLineItem": "g47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "addons": [
      {
        "productOfferingId": "<string>",
        "productOffering": {
          "productOfferingId": "<string>",
          "name": "<string>",
          "price": {
            "grossPrice": 10,
            "discount": 123,
            "netPrice": 5,
            "currency": "USD",
            "priceType": "ONE_TIME",
            "boundMonths": 12,
            "billingCycle": {
              "period": "MONTHLY",
              "interval": 1
            },
            "taxIncluded": true
          },
          "productOfferingGroupId": "<string>",
          "group": {
            "productOfferingGroupId": "<string>",
            "name": "<string>",
            "category": "SUBSCRIPTION_CELL"
          }
        },
        "status": "PENDING",
        "productOfferingGroupId": "<string>",
        "group": {
          "productOfferingGroupId": "<string>",
          "name": "<string>",
          "category": "SUBSCRIPTION_CELL"
        },
        "licenseId": "<string>",
        "pendingStatus": {
          "status": "PENDING",
          "scheduledAt": "2023-12-25"
        },
        "addedAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "cancelledAt": "2023-11-07T05:31:56Z",
        "metadata": {},
        "createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "modifications": [
      {
        "type": "SUBSCRIPTION_CHANGE",
        "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "newProductOfferingId": "po_mobile_premium_plus",
        "appliedAt": "2023-11-07T05:31:56Z",
        "createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ]
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {}
}

Authorizations

​
X-API-Key
string
header
required

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

Headers

​
X-Idempotency-Key
string

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.

Maximum length: 256

Body

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

​
user
object

The user who will use the services in this order. To create a new user, provide their details. For a returning user, provide their user ID.

  • ExistingUser
  • NewUser
​
customer
object

Reference to a customer of the order, either an existing customer or to set up a new customer.

  • ExistingCustomer
  • NewCustomer
​
billing
object

Billing information for an order.

For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.

​
shipping
object

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

​
lineItems
(Subscription · object | License · object | Add-on · object | Top-up · object | External Product · object | External Item · object | Subscription Change · object | License Change · object | Add-on Change · object)[]

Initial line items for the order (can be empty).

  • Subscription
  • License
  • Add-on
  • Top-up
  • External Product
  • External Item
  • Subscription Change
  • License Change
  • Add-on Change
​
promoCode
string

Promo code to apply to the order.

Example:

"SUMMER2023"

​
metadata
object

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

Response

Order created successfully

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

​
orderId
string
required

Unique identifier for the order.

Example:

"order-123"

​
status
enum<string>
required

The status of an order in its lifecycle.

  • PENDING: Order is in cart state, can be modified
  • CONFIGURED: Order is complete and ready for submission
  • SUBMITTED: Order has been submitted for processing
  • PENDING_APPROVAL: Order is pending approval
  • PROCESSING: Order is being fulfilled
  • COMPLETED: Order has been successfully fulfilled
  • CANCELLED: Order was cancelled before completion
  • EXPIRED: Order expired due to inactivity
Available options:
PENDING,
CONFIGURED,
SUBMITTED,
PENDING_APPROVAL,
PROCESSING,
COMPLETED,
CANCELLED,
EXPIRED
​
lineItems
(Subscription · object | License · object | Add-on · object | Top-up · object | External Product · object | External Item · object | Subscription Change · object | License Change · object | Add-on Change · object)[]
required

Line items in the order.

  • Subscription
  • License
  • Add-on
  • Top-up
  • External Product
  • External Item
  • Subscription Change
  • License Change
  • Add-on Change
​
createdAt
string<date-time>
required

When the order was created.

Example:

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

​
updatedAt
string<date-time>
required

When the order was last updated.

Example:

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

​
user
object

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

​
customer
object

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

​
billing
object

Billing information for an order.

For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.

​
shipping
object

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

​
promoCode
string

Promotional code applied to this order, if any.

Example:

"STUDENT2024"

​
consents
object

Customer consents and acknowledgments.

Example:
{
  "termsOfService": "true",
  "marketing": "true"
}
​
pricing
object

The price of an order. In regions with complex tax rules (e.g., the US), you need to call the price calculation endpoint to get accurate tax amounts before submitting the order. In other regions, tax is dependent on customer type but typically included.

​
validation
object

Validation status of the order and its line items.

​
requirements
object

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

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

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

​
expiresAt
string<date-time>

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

Example:

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

​
submittedAt
string<date-time>

When the order was submitted for fulfillment.

Example:

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

​
completedAt
string<date-time>

When the order was completed.

Example:

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

​
createdEntities
object

Entities created as part of order fulfillment.

​
metadata
object

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

⌘I