# Notify the order customer

Sends the customer of an order an email in the store name, or a fixed text message from the merchant's package.

```http
POST https://larm.sa/stores/{storeId}/v1/orders/{id}/notifications
```

Scope: `customers.notify:write`

An **email** has your own `subject` (3 to 160 characters) and `body` (up to 5,000 characters), appears in the order's message log, and is limited to 60 messages an hour per store.

A **text message** has fixed wording, because the sender is a registered service sender, so free text is not accepted. Choose a `template`: `order_shipped`, `out_for_delivery` or `delivered`. Each template goes once per order and is charged to the merchant's message package, and the merchant can turn any of them off.

The `status` of a text message is `sent`, `already_sent` (sent before and not charged again) or `retrying` (the store is retrying by itself, so do not send it again). The `status` of an email is `sent`, `pending` (the store is retrying by itself, so do not send it again) or `failed` (it could not be delivered and the store stopped trying). See [Marketing and customer messages](/guides/messaging).

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |


## Headers

| Field | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | yes |  |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.order_id` | string | no |  |
| `data.channel` | string | no | One of: `email`, `sms`. |
| `data.template` | string | no | One of: `order_shipped`, `out_for_delivery`, `delivered`. |
| `data.status` | string | no | For a text message: sent, already_sent or retrying. For an email: sent, pending or failed. |
| `execution` | object | no | Who executed the request: the app, version, installation and store. Field names here are camelCase. |
| `execution.appId` | string (uuid) | no |  |
| `execution.versionId` | string (uuid) | no |  |
| `execution.installationId` | string (uuid) | no |  |
| `execution.storeId` | string (uuid) | no |  |
| `execution.requestId` | string (uuid) | no |  |
| `execution.generation` | integer | no |  |
| `execution.routeEpoch` | integer | no |  |
| `execution.appAuthEpoch` | integer | no |  |
| `execution.grantRevision` | integer | no |  |
| `meta` | object | yes |  |
| `meta.request_id` | string (uuid) | no | The request ID; include it in any support request. |


## Example request

```bash
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/orders/200123/notifications" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $UUID" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "template": "out_for_delivery" }'
```


## Example response (200)

```json
{
  "data": {
    "order_id": "200123",
    "channel": "sms",
    "template": "out_for_delivery",
    "status": "sent"
  },
  "execution": {
    "appId": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
    "versionId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "installationId": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d",
    "storeId": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10",
    "requestId": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a",
    "generation": 1,
    "routeEpoch": 4,
    "appAuthEpoch": 1,
    "grantRevision": 2
  },
  "meta": {
    "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a"
  }
}
```


## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | No Idempotency-Key header. |
| 404 | `RESOURCE_NOT_FOUND` | The ID does not exist in this store. |
| 409 | `CUSTOMER_EMAIL_MISSING` | The order has no customer email. |
| 409 | `CUSTOMER_PHONE_MISSING` | The order has no valid customer phone. |
| 409 | `SMS_NOT_ENABLED` | The merchant turned this message off, or the store has no message package. |
| 409 | `SMS_NO_BALANCE` | The merchant's message package is empty. |
| 409 | `SMS_NOT_SENT` | The message could not be sent. |
| 409 | `SHIPPING_ORDER_NOT_ELIGIBLE` | A text message for an order that is unpaid, cancelled, refunded, or has nothing to ship. |
| 422 | `INVALID_NOTIFICATION_CHANNEL` | channel is not email or sms. |
| 422 | `INVALID_NOTIFICATION_TEMPLATE` | Unknown template. |
| 422 | `INVALID_INPUT` | The email subject or body is outside its limits. |
| 429 | `MESSAGE_LIMIT_REACHED` | The store reached 60 emails this hour. |
| 403 | `SCOPE_REQUIRED` | The token does not carry the required scope. |
| 503 | `APPS_SCOPE_RUNTIME_NOT_READY` | The resource is not enabled on this merchant's store yet. |