telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Get started

Place your first order with the Seamless OS API

Get your first order

This guide takes you through your first order on the Seamless OS API. You authenticate, read the products, create an order, collect the payment, and submit the order for provisioning.

Authentication

Every request needs an API key in the X-API-Key header. For the full rules, read the Authentication guide.

Quick path

  1. List product offerings

    Get the offerings that you can show to a customer.

  2. Create order

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

  3. Read price

    Read the taxes and the total off the order before the payment.

  4. Create payment link

    Generate a payment link to collect the prepaid funds.

  5. Submit order

    Lock the paid order for provisioning.

1. List product offerings

Get the product offerings that you can present to your customers. The response gives the plans, the prices, and the features that a customer can buy.

curl "{BASE_URL}/products/offerings" \
  -H "X-API-Key: $API_KEY"
const response = await fetch('{BASE_URL}/products/offerings', {
  headers: {
    'X-API-Key': process.env.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 the customer, the subscriber, and the selected product offering. A draft order carries no price and no confirmation yet.

curl -X POST "{BASE_URL}/orders" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 order = await fetch('{BASE_URL}/orders', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.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

3. Read the order price

The platform calculates the taxes and the total again each time the order changes, and returns them as pricing on the order. Read them before you collect the payment. On a US purchase, the tax is calculated per jurisdiction from the addresses on the order.

curl "{BASE_URL}/orders/{orderId}" \
  -H "X-API-Key: $API_KEY"
const orderResponse = await fetch(`{BASE_URL}/orders/${newOrder.orderId}`, {
  headers: {
    'X-API-Key': process.env.API_KEY,
  },
});

const pricedOrder = await orderResponse.json();
console.log('Order total:', pricedOrder.pricing.totalMinor / 100, pricedOrder.pricing.currency);

See Get Order

Create a payment link for the order. The amount comes from the calculated price of the order, so you never send an amount yourself. The link opens a hosted page where the customer pays.

curl -X POST "{BASE_URL}/payment-links" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "{orderId}",
    "returnUrl": "https://yourapp.com/payment/success",
    "cancelUrl": "https://yourapp.com/payment/cancel"
  }'
const paymentLink = await fetch('{BASE_URL}/payment-links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: newOrder.orderId,
    returnUrl: 'https://yourapp.com/payment/success',
    cancelUrl: 'https://yourapp.com/payment/cancel',
  }),
});

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

See Create Payment Link

5. Submit order

After the payment succeeds, submit the order. The submit locks the price and starts provisioning.

curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
  -H "X-API-Key: $API_KEY"
const submitted = await fetch(`{BASE_URL}/orders/${newOrder.orderId}/submit`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY,
  },
});

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

See Submit Order

6. Read the result

Get the new subscription and make sure that it is active:

# Fetch the full subscription details
curl "{BASE_URL}/subscriptions/{subscriptionId}" \
  -H "X-API-Key: $API_KEY"
// Get the subscription ID from the created entities
const subscriptionId = submittedOrder.createdEntities.subscriptions[0].subscriptionId;

// Fetch the full subscription details
const subscription = await fetch(`{BASE_URL}/subscriptions/${subscriptionId}`, {
  headers: {
    'X-API-Key': process.env.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);

You placed your first order on the Seamless OS API.

Next steps

Conventions

The design principles and the naming patterns of the API.

Authentication

API keys, user tokens, and how to keep them safe.

Versioning

The revision your key is pinned to, and when you move it.

Payment links

The payment flow in full.

Webhooks

Configure event notifications for an order.

Contact support

Write to our support team.