> 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sms4sats.com/api-reference/create-send-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.