> 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-send-order.md).

# Create Send Order

<mark style="color:green;">`POST`</mark> `https://api2.sms4sats.com/createsendorder`

Creates an order to send an SMS message to any E.164 phone number. Returns a Lightning invoice to pay, or immediately sends the SMS if using a pre-funded API Key.

#### Headers

| Name        | Type   | Required | Description                                                    |
| ----------- | ------ | -------- | -------------------------------------------------------------- |
| `X-API-Key` | String | No       | API Key for pre-funded account. Required if `immediate: true`. |

#### Request Body

| Name         | Type    | Required | Description                                                                                                           |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `message`    | String  | Yes      | Message text to send. Maximum 140 characters.                                                                         |
| `phone`      | String  | Yes      | Destination phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) (e.g. `+19871234567`).                |
| `immediate`  | Boolean | No       | Set to `true` to send immediately and deduct cost from your API Key balance.                                          |
| `webhookUrl` | String  | No       | URL to receive order status updates via `POST`. Same payload as [`/orderstatus`](/api-reference/get-order-status.md). |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp5... | paid'
}
```

{% endcode %}
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'backend error'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                                                                                      |
| --------- | ------ | ------------------------------------------------------------------------------------------------ |
| `status`  | String | `OK` on success                                                                                  |
| `orderId` | String | Unique order ID — use with [Get Order Status](/api-reference/get-order-status.md)                |
| `payreq`  | String | BOLT11 Lightning invoice, or `"paid"` if `immediate: true` and payment was deducted from balance |

### Checking Delivery Status

Use [Get Order Status](/api-reference/get-order-status.md) with the returned `orderId` to monitor send progress. The `smsStatus` field will reflect `created → sent → delivered` (or `failed`).

{% hint style="success" %}
For send orders, the hold invoice is only settled once the SMS status is `sent` or `delivered`. If delivery fails, the invoice is canceled and funds returned.
{% endhint %}