> ## Documentation Index
> Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started

> Get your first order with the SeamlessOS API in minutes

# Get Your First Order

This guide walks you through creating your **first order** using the SeamlessOS API. You'll authenticate, browse products, create an order, handle payment, and submit for provisioning.

## Authentication

Every request requires an API key in the `X-API-Key` header. See the [Authentication guide](https://telnesstech-a0a16404.mintlify.site/api-reference/authentication.md) for complete details.

## Quick Path

**1. List Product Offerings**

Fetch available product offerings to display to customers.

**2. Create Order**

Start an order with customer, subscriber, and product details.

**3. Calculate Price**

Calculate taxes and totals before payment.

**4. Create Payment Link**

Generate a payment link to collect prepaid funds.

**5. Submit Order**

Lock in the paid order for provisioning.

## 1. List Product Offerings

Fetch available product offerings to present to your customers. This shows plans, pricing, and features they can purchase.

```javascript theme={null}
const response = await fetch('https://connect.telnesstech.com/api/v2/products/offerings', {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY
  }
});

const offerings = await response.json();
console.log('Available offerings:', offerings.items);
```

See [List Product Offerings](https://telnesstech-a0a16404.mintlify.site/api-reference/product-offerings/list-product-offerings.md)

## 2. Create Order

Create a draft order with customer details, subscriber information, and the selected product offering. At this stage, the order is not yet priced or confirmed.

```javascript theme={null}
const order = await fetch('https://connect.telnesstech.com/api/v2/orders', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: {
      customerId: '123e4567-e89b-12d3-a456-426614174000'
    },
    lineItems: [{
      type: 'SUBSCRIPTION',
      lineItemId: 'line-1',
      productOfferingId: '456a789b-cd12-34ef-567g-890123456789',
      subscriber: {
        name: 'John Doe',
        email: 'john@acme.com'
      },
      sim: {
        esim: true
      }
    }]
  })
});

const newOrder = await order.json();
console.log('Created order:', newOrder.orderId);
```

See [Create Order](https://telnesstech-a0a16404.mintlify.site/api-reference/orders/create-order.md)

## 3. Calculate Order Price

Calculate taxes and totals for the order before collecting payment. For US-based purchases, pricing is calculated at the jurisdiction level.

```javascript theme={null}
const priceCalculation = await fetch(`https://connect.telnesstech.com/api/v2/orders/${newOrder.orderId}/calculate-price`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  }
});

const pricedOrder = await priceCalculation.json();
console.log('Order total:', pricedOrder.pricing.total);
```

See [Calculate Order Price](https://telnesstech-a0a16404.mintlify.site/api-reference/orders/calculate-order-price.md)

## 4. Create Payment Link

Generate a payment link for the calculated amount. This creates a hosted payment page where customers can complete their payment.

```javascript theme={null}
const paymentLink = await fetch('https://connect.telnesstech.com/api/v2/payment-links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    orderId: newOrder.orderId,
    amount: pricedOrder.pricing.total,
    currency: 'USD',
    returnUrl: 'https://yourapp.com/payment/success',
    cancelUrl: 'https://yourapp.com/payment/cancel'
  })
});

const link = await paymentLink.json();
console.log('Payment URL:', link.url);
// Redirect user to link.url for payment
```

See [Create Payment Link](https://telnesstech-a0a16404.mintlify.site/api-reference/payment-links/create-payment-link.md)

## 5. Submit Order

Once payment has been successfully collected, submit the order to lock in pricing and trigger provisioning.

```javascript theme={null}
const submitted = await fetch(`https://connect.telnesstech.com/api/v2/orders/${newOrder.orderId}/submit`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY
  }
});

const submittedOrder = await submitted.json();
console.log('Order submitted:', submittedOrder.status);
```

See [Submit Order](https://telnesstech-a0a16404.mintlify.site/api-reference/orders/submit-order.md)

## 6. Check Results

Fetch the created subscription to verify it was successfully activated:

```javascript theme={null}
// Get the subscription ID from the created entities
const subscriptionId = submittedOrder.createdEntities.subscriptions[0].subscriptionId;

// Fetch the full subscription details
const subscription = await fetch(`https://connect.telnesstech.com/api/v2/subscriptions/${subscriptionId}`, {
  headers: {
    'X-API-Key': process.env.CONNECT_API_KEY
  }
});

const subscriptionDetails = await subscription.json();
console.log('Subscription ID:', subscriptionDetails.subscriptionId);
console.log('Status:', subscriptionDetails.status);
console.log('Phone Number:', subscriptionDetails.msisdn);
console.log('Subscriber:', subscriptionDetails.subscriber.name);
```

That's it! You've successfully created your first order through the SeamlessOS API.

## Next Steps

> [card] [API Conventions](https://telnesstech-a0a16404.mintlify.site/api-reference/conventions.md)
>
> Understand our design principles and patterns.

> [card] [Authentication](https://telnesstech-a0a16404.mintlify.site/api-reference/authentication.md)
>
> Complete authentication and security guide.

> [card] [Payment Links](https://telnesstech-a0a16404.mintlify.site/api-reference/payment-links)
>
> Deep dive into payment flow handling.

> [card] [Webhooks](https://telnesstech-a0a16404.mintlify.site/api-reference/webhooks.md)
>
> Set up real-time notifications for order updates.

> [card] [Contact support](https://telnesstech.com/contact)
>
> Get in touch with our support team for assistance


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.