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

# Create Receive Order

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

Creates a new receive SMS order. Returns an `orderId` and a Lightning invoice (`payreq`). Pay the invoice to activate the order and start waiting for an SMS.

#### Request Body

| Name        | Type    | Required | Description                                                                                                        |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `country`   | Number  | Yes      | Country code (e.g. `187` for USA). See [Get Countries](/api-reference/get-countries.md).                           |
| `service`   | String  | Yes      | Service short code (e.g. `vk`). Use `value` from [Get Available Services](/api-reference/get-services.md).         |
| `isRental`  | Boolean | No       | Set to `true` for a phone number rental order.                                                                     |
| `realphone` | Boolean | No       | Set to `true` for a real phone number from the sms4sats network.                                                   |
| `ref`       | String  | No       | A valid [Lightning Address](https://lightningaddress.com) to receive 10% referral payments for this order.         |
| `immediate` | Boolean | No       | Set to `true` to deduct cost from your API Key balance instead of issuing an invoice. Requires `X-API-Key` header. |

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

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

{% endcode %}
{% endtab %}

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

```javascript
{
    status: 'error',
    reason: 'unable to save data'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `status`  | String | `OK` on success                                      |
| `orderId` | String | Unique order ID — use this to check status or cancel |
| `payreq`  | String | BOLT11 Lightning invoice to pay                      |

### Next Steps

1. Pay the `payreq` invoice using any Lightning wallet.
2. Poll [Get Order Status](/api-reference/get-order-status.md) with the `orderId` until `code` appears in the response.
3. Optionally [Cancel Order](/api-reference/cancel-order.md) after 2 minutes if no code has arrived.

{% hint style="success" %}
sms4sats uses [hold invoices](https://bolt.fun/guide/invoices/hodl-invoice). Payment is only settled when an activation code is successfully delivered. If no code arrives within 21 minutes, the invoice is automatically canceled and funds returned.
{% endhint %}