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

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

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.

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: '[e-mail]'
      },
      sim: {
        esim: true
      }
    }]
  })
});

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

See Create Order

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.

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

4. Create Payment Link

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

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

5. Submit Order

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

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

6. Check Results

Fetch the created subscription to verify it was successfully activated:

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

API Conventions

Understand our design principles and patterns.

Authentication

Complete authentication and security guide.

Payment Links

Deep dive into payment flow handling.

Webhooks

Set up real-time notifications for order updates.

Contact support

Get in touch with our support team for assistance