Submit order

Submit an order for fulfillment. Requires payment, signing, or card capture, depending on the setup.

POST /orders/{orderId}/submit

Submit order

cURL

curl --request POST \
  --url https://apiv2.example.com/orders/{orderId}/submit \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "paymentSessionId": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
  "paymentProfileSessionId": "b2c3d4e5-f6a7-8901-2345-6789abcdef01",
  "signingSessionId": "c3d4e5f6-a7b8-9012-3456-789abcdef012",
  "metadata": {}
}
'

200

{
  "orderId": "order-123",
  "state": "PENDING",
  "lineItems": [
    {
      "type": "SUBSCRIPTION",
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "msisdn": "[phone]",
      "leaseToken": "<string>",
      "tempNumber": true,
      "portingRequested": true,
      "porting": {
        "details": {
          "firstName": "<string>",
          "lastName": "<string>",
          "address": {
            "street1": "500 S Main St",
            "city": "Natick",
            "zip": "01701",
            "country": "US",
            "street2": "Apt 1",
            "state": "CA",
            "region": "<string>",
            "attention": "<string>"
          },
          "accountNumber": "<string>",
          "passcode": "<string>"
        }
      },
      "extensions": {},
      "display": "<string>",
      "subscriber": {
        "name": "John Doe",
        "email": "[e-mail]",
        "msisdn": "[phone]",
        "address": {
          "street1": "500 S Main St",
          "city": "Natick",
          "zip": "01701",
          "country": "US",
          "street2": "Apt 1",
          "state": "CA",
          "region": "<string>",
          "attention": "<string>"
        }
      },
      "sim": {
        "esim": true,
        "imei": "356938035643809",
        "iccid": "8931440400000000000"
      },
      "scheduleActivationAt": "2024-02-01",
      "metadata": {},
      "status": "PENDING"
    }
  ],
  "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",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "user": {
    "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
    "newUser": true,
    "name": "John Doe"
  },
  "customer": {
    "customerType": "CONSUMER",
    "name": "John Doe",
    "newCustomer": true,
    "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "billing": {
    "name": "John Doe",
    "email": "[e-mail]",
    "address": {
      "street1": "500 S Main St",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "street2": "Apt 1",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    }
  },
  "shipping": {
    "name": "John Doe",
    "address": {
      "street1": "500 S Main St",
      "city": "Natick",
      "zip": "01701",
      "country": "US",
      "street2": "Apt 1",
      "state": "CA",
      "region": "<string>",
      "attention": "<string>"
    },
    "msisdn": "[phone]",
    "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"
  },
  "pricing": {
    "total": 137.39,
    "currency": "USD",
    "calculatedAt": "2024-01-15T10:30:00Z",
    "subtotal": 125.99,
    "taxAmount": 10.08,
    "fees": 1.32,
    "taxIncluded": true,
    "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"
      }
    }
  },
  "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"
  },
  "submittedAt": "2024-01-15T14:30:00Z",
  "completedAt": "2024-01-15T15:00:00Z",
  "createdEntities": {
    "subscriptions": [
      {
        "subscriptionId": "<string>",
        "status": "PENDING",
        "type": "<string>",
        "display": "<string>",
        "msisdn": "<string>",
        "customerId": "<string>",
        "productOfferingId": "<string>",
        "subscriberId": "<string>",
        "activatedAt": "2023-11-07T05:31:56Z",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "cancelledAt": "2023-11-07T05:31:56Z"
      }
    ],
    "licenses": [
      {
        "licenseId": "<string>",
        "status": "PENDING",
        "type": "<string>",
        "customerId": "<string>",
        "productOfferingId": "<string>",
        "activatedAt": "2023-11-07T05:31:56Z",
        "createdByLineItem": "g47ac10b-58cc-4372-a567-0e02b2c3d479",
        "assignedTo": {
          "type": "SUBSCRIPTION",
          "subscriptionId": "<string>"
        },
        "cancelledAt": "2023-11-07T05:31:56Z",
        "pausedAt": "2023-12-25"
      }
    ],
    "addons": [
      {
        "status": "PENDING",
        "createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479",
        "productOfferingId": "<string>",
        "referenceId": "telna-package-12345",
        "productOfferingGroupId": "<string>",
        "licenseId": "<string>",
        "addedAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "cancelledAt": "2023-11-07T05:31:56Z",
        "metadata": {}
      }
    ],
    "modifications": [
      {
        "type": "SUBSCRIPTION_CHANGE",
        "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479",
        "newProductOfferingId": "po_mobile_premium_plus",
        "appliedAt": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "metadata": {}
}

Authorizations

apiKeybearerAuth & apiKey

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 string length: 256

Path Parameters

orderId · string · required

The unique identifier of the order

Body

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

paymentSessionId · string

Reference to completed payment session for orders requiring payment collection.

Example:

"a1b2c3d4-e5f6-7890-1234-56789abcdef0"

paymentProfileSessionId · string

Reference to completed payment profile session for zero-total orders requiring payment method setup.

Example:

"b2c3d4e5-f6a7-8901-2345-6789abcdef01"

signingSessionId · string

Reference to completed signing session.

Example:

"c3d4e5f6-a7b8-9012-3456-789abcdef012"

externalPayment · object

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

metadata · object

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

Show child attributes

Response

200

application/json

Order submitted successfully

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

orderId · string · required

Unique identifier for the order.

Example:

"order-123"

state · enum<string> · required

The status of an order in its lifecycle.

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

Available options: PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED

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

Line items in the order.

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

Subscription

License

Add-on

External Product

External Item

Subscription Change

License Change

Add-on Change

Show child attributes

validation · object · required

Validation status of the order and its line items.

Show child attributes

requirements · object · required

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

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

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

Show child attributes

expiresAt · string<date-time> · required

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

Example:

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

createdAt · string<date-time> · required

When the order was created.

Example:

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

updatedAt · string<date-time> · required

When the order was last updated.

Example:

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

user · object

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

Show child attributes

customer · object

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

Show child attributes

billing · object

Billing information for an order.

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

Show child attributes

shipping · object

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

Show child attributes

promoCode · string

Promotional code applied to this order, if any.

Example:

"STUDENT2024"

paymentSessionId · string

The payment session that collected payment for this order, set when the order was submitted with one.

Example:

"d2e3f4a5-b6c7-8901-2345-012345678901"

paymentProfileSessionId · string

The payment profile session used to set up a payment method for this order, set when the order was submitted with one.

Example:

"69321a62-f1fe-461f-8761-a19ae6587bb2"

signingSessionId · string

The signing session that captured the customer's signature for this order, set when the order was submitted with one.

Example:

"8f3b1c2d-4e5f-6789-abcd-1234567890ef"

consents · object

Customer consents and acknowledgments.

Show child attributes

Example:

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

pricing · object

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

Show child attributes

externalPayment · object

External payment details if the order was paid outside the system.

Show child attributes

submittedAt · string<date-time>

When the order was submitted for fulfillment.

Example:

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

completedAt · string<date-time>

When the order was completed.

Example:

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

createdEntities · object

Entities created as part of order fulfillment.

Show child attributes

metadata · object

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

Show child attributes