Connect API Mental Model

Connect becomes much easier to use once you understand 3 core concepts:

The resource model
Asynchronous provisioning
Webhook-driven lifecycle updates

The e-commerce analogy

Think of Connect like an e-commerce platform for telecom services:

Product Offering = the plan displayed in your catalog

Order = the checkout action

Product = the provisioned service the customer receives

Subscription = the active connectivity lifecycle you manage

Most integrations follow the same pattern:

Choose what to sell
Define who is buying
Place an Order
Wait for provisioning
Track lifecycle changes through webhooks

The Core Provisioning Flow

Most integrations follow this sequence:

Product Offering → Account → Subscriber → Order → Product → Subscription → SIM Profile

This represents the lifecycle of provisioning connectivity through Connect.

Resource Model

Ownership Hierarchy

Before diving in, here's how the concepts you already use in your business map to Connect resources:

In your business	In Connect	Typical cardinality
Paying customer or organization	Account	1
User or device that consumes connectivity	Subscriber	1..N per Account
A connectivity plan	Subscription	1..N per Subscriber

The three form a strict ownership hierarchy:

Account      ← the paying customer / organization
└── Subscriber   ← a user or device that consumes connectivity
    └── Subscription  ← a connectivity plan

Rule of thumb:

One Account per paying customer.
One Subscriber per user or device that consumes connectivity.
One Subscription per connectivity plan.

Resource References

Subscriptions reference the provisioned connectivity resources:

Subscription → Product → Product Offering
Subscription → SIM Profile

Store all returned resource IDs in your system. They are required for support, lifecycle management, and operational troubleshooting.

Core Resources

The Connect API is resource-oriented. Most integrations start with catalog and provisioning resources, then expand into renewals, number portability, billing, and webhook-driven lifecycle updates.

Catalog & Commercialization

Resource	Prefix	Description
Product Catalog	`prdcat_`	Organized collection of sellable connectivity plans
Product Offerings	`prdoff_`	Commercial plans, bundles, and add-ons available for purchase
Coverage Areas	`cov_`	Geographic or network coverage constraints for offerings

Identity, Provisioning & Lifecycle

Resource	Prefix	Description
Accounts	`acc_`	Paying customer or organization that owns subscribers and billing
Subscribers	`subr_`	End users or devices that consume connectivity
Orders	`ord_`	Purchase and lifecycle change requests (provision, modify, cancel)
Products	`prd_`	Provisioned instances created after a successful order
Subscriptions	`subs_`	Active connectivity lifecycle, balances, and service state
SIM Profiles	`simp_`	eSIM or physical SIM profiles used for connectivity
Verifications	`vrf_`	Short-lived one-time-code sessions used to confirm end-user actions such as phone number verification

Recurring & Renewals

Resource	Prefix	Description
Renewal Groups	`rnwgrp_`	Container that manages recurring prepaid renewal cycles for a product
Renewals	`rnw_`	Individual renewal cycles within a group (pending, scheduled, completed)

Numbers & Portability

Resource	Prefix	Description
Phone Numbers	`pn_`	MSISDN resources assigned to subscriptions
Portings	`port_`	Number portability workflows when customers keep their existing number
Files	`file_`	Uploaded documents that support business processes such as porting authorization

Billing, Compliance & Operations

Resource	Prefix	Description
Invoices	`inv_`	Itemized billing documents for accounts and subscriptions
Credit Notes	`cn_`	Refunds, corrections, and billing adjustments against invoices
Discounts	`dis_`	Discount configurations applied to invoices and recurring charges
Contracts	`con_`	Contract summaries and compliance artifacts (where required)

Integration

Resource	Prefix	Description
Webhooks	`wbh_`	Webhook endpoint configurations used to receive lifecycle notifications
Events	`evt_`	Webhook events emitted asynchronously for provisioning and lifecycle changes

Product Offering vs Product

This is one of the most important concepts in Connect.

Product Offering

A Product Offering is the commercial template you sell.

Example:

Europe 5GB
30 days
€10

It exists in the catalog and is shared across all customers.

Product

A Product is the provisioned instance created after a successful Order.

Example:

Europe 5GB
Assigned to subscriber subr_123
Activated on 2026-05-20

In short:

You display and sell Product Offerings
Customers consume Products

Orders Are Asynchronous

POST /orders starts provisioning work, but provisioning completes asynchronously.

Typical Order lifecycle:

accepted → in_progress → completed
                           ↘ failed

A typical sequence looks like this:

Your Backend → POST /orders → 202 Accepted
Connect provisions connectivity asynchronously
Connect → webhook → order.completed

The initial API response confirms the request was accepted.

Webhook events confirm the final provisioning result.

Common Mistake

Polling GET /orders/{id} waiting for eSIM installation details

Correct approach:

Wait for order.completed to confirm the Order was completed successfully
Wait for subscription.sim_profile.ready_for_installation to receive the eSIM installation details
Deliver the installation details to the end user
Use subscription.sim_profile.installed to know when the eSIM has been installed on the device

order.completed means the Order completed successfully. It does not mean the end user has installed the eSIM.

Webhook-First Architecture

Connect is designed around asynchronous lifecycle events.

Your integration should treat webhooks as the primary source of truth for provisioning completion and lifecycle updates.

Common webhook events include:

order.completed
order.failed
subscription.sim_profile.ready_for_installation
subscription.sim_profile.installed

Typical provisioning flow:

You create an Order
Connect starts provisioning
Webhooks notify your backend as states change
Your system updates the customer experience

You must expose an HTTPS endpoint capable of receiving webhook events.

Production Integration Rules

When building production integrations:

Always send Idempotency-Key on supported write operations
Always send Correlation-Id for observability and support
Prefer webhooks over aggressive polling
Store all resource IDs returned by the API
Handle failure states such as order.failed

Next Steps

Start with Quickstart if you have not provisioned your first eSIM yet
Explore Recipes for end-to-end business flows
Browse the API Reference for resource details and schemas
Review Go to Production before launch

On this page