> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/api-reference/create-order.md).

# Create a Bearer-Token Order

Create an idempotent receive-SMS or rental order and receive its hold invoice and access token.

{% tabs %}
{% tab title="Receive SMS" %} <mark style="color:green;">`POST`</mark> `/v2/receive-sms/orders`
{% endtab %}

{% tab title="Rent Number" %} <mark style="color:green;">`POST`</mark> `/v2/rent-numbers/orders`
{% endtab %}
{% endtabs %}

## Headers

| Header                           | Required | Description                                   |
| -------------------------------- | -------- | --------------------------------------------- |
| `Content-Type: application/json` | Yes      | JSON request body                             |
| `Idempotency-Key: <UUID v4>`     | Yes      | Random UUID v4 scoped to the selected product |

`X-Idempotency-Key` is accepted as an equivalent header. Prefer `Idempotency-Key`.

## Body

| Field             | Type    | Receive      | Rental   | Description                                           |
| ----------------- | ------- | ------------ | -------- | ----------------------------------------------------- |
| `country`         | string  | Required     | Required | `auto`, numeric ID, ISO code, or country name         |
| `service`         | string  | Required     | Required | Service code or recognized name                       |
| `durationMinutes` | integer | Ignored/omit | Optional | 1–43,200; normalized to at least 120 and a whole hour |
| `referral`        | string  | Optional     | Optional | Maximum 320 characters                                |
| `clientRequestId` | string  | Optional     | Optional | Client correlation value, maximum 200 characters      |

The endpoint path determines the product type. Do not send a conflicting `type` field.

## Example

```bash
curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 17165eb7-d770-4a21-abd4-90295ac15252' \
  -d '{"country":"US","service":"tg","clientRequestId":"checkout-123"}'
```

Response: HTTP `201 Created`

```json
{
  "orderId": "<payment-hash>",
  "accessToken": "<opaque-token>",
  "orderReference": "<payment-hash>.<opaque-token>",
  "invoice": "lnbc...",
  "priceSats": 350,
  "status": "pending_payment"
}
```

## Idempotent retries

* Same key + same normalized body: returns the original order and invoice.
* Same key + different body: `409 IDEMPOTENCY_CONFLICT`.
* Concurrent retry while creation is running: `409 IDEMPOTENCY_IN_PROGRESS`; retry the same request and key after a short delay.
* Network timeout or ambiguous `5xx`: retry the same request and key. Never generate a new key until you know the original request did not create an order.

{% hint style="danger" %}
`accessToken` is returned as a secret order capability. Persist it before navigating away. `orderReference` packages the order ID and token for client-side portability; it is equally sensitive.
{% endhint %}