Skip to main content
POST
/
orders
/
{orderId}
/
cancel
{
  "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.

Path Parameters

​
orderId
string
required

The unique identifier of the order

Body

application/json
​
cancellationReason
string

Optional reason for cancelling the order.

Example:

"Customer changed their mind"

​
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 cancelled 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