---
title: Get started
description: 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](/api-reference/authentication.md).

## 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. Calculate price**

Calculate the taxes and the total 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.

```bash
curl "{BASE_URL}/products/offerings" \
  -H "X-API-Key: $API_KEY"
```

See [List Product Offerings](/api-reference/product-offerings.md#tag/product-offerings/GET/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.

```bash
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
        }
      }
    ]
  }'
```

See [Create Order](/api-reference/orders.md#tag/orders/POST/orders)

## 3. Calculate order price

Calculate the taxes and the total for the order before you collect the payment. On a US
purchase, the price is calculated per tax jurisdiction.

```bash
curl -X POST "{BASE_URL}/orders/{orderId}/calculate-price" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json"
```

See [Calculate Order Price](/api-reference/orders.md#tag/orders/POST/orders/{orderId}/calculate-price)

## 4. Create payment link

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.

```bash
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"
  }'
```

See [Create Payment Link](/api-reference/payment-links.md#tag/payment-links/POST/payment-links)

## 5. Submit order

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

```bash
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
  -H "X-API-Key: $API_KEY"
```

See [Submit Order](/api-reference/orders.md#tag/orders/POST/orders/{orderId}/submit)

## 6. Read the result

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

```bash
# Fetch the full subscription details
curl "{BASE_URL}/subscriptions/{subscriptionId}" \
  -H "X-API-Key: $API_KEY"
```

You placed your first order on the Seamless OS API.

## Next steps

- [Conventions](/api-reference/conventions.md) — The design principles and the naming patterns of the API.
- [Authentication](/api-reference/authentication.md) — API keys, user tokens, and how to keep them safe.
- [Payment links](/resources/payment-links.md) — The payment flow in full.
- [Webhooks](/api-reference/webhooks.md) — Configure event notifications for an order.
- [Contact support](https://telnesstech.com/contact) — Write to our support team.