# Replace delivery options

Replaces your app's whole list, up to 10 options. Send an empty list to remove them all.

```http
POST https://larm.sa/stores/{storeId}/v1/delivery-options
```

Scope: `shipping.options:write`

Customers see an option only after the merchant turns it on. A changed price or company name turns it off again until the merchant reviews it. See [Delivery companies](/guides/delivery-companies).

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | array<object> | yes | Replaces your app's whole list. |
| `options[].key` | string | yes | A stable key for the option inside your app. |
| `options[].company_name` | string | yes | The company name the customer sees. |
| `options[].label` | string | yes | The name the customer sees. |
| `options[].eta` | string \| null | no | The delivery time as the customer reads it. |
| `options[].price` | string | yes | The price in SAR, from 0 to 1000. |
| `options[].cities` | array<string> | no | The cities covered, in Arabic as customers write them; an empty list means every city in Saudi Arabia. |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array<object> | yes |  |
| `data[].key` | string | no | A stable key for the option inside your app. |
| `data[].company_name` | string | no | The company name the customer sees. |
| `data[].label` | string | no | The name the customer sees. |
| `data[].eta` | string \| null | no | The delivery time as the customer reads it. |
| `data[].price` | string | no | Price in SAR. |
| `data[].cities` | array<string> | no | The cities covered, in Arabic as customers write them; an empty list means every city in Saudi Arabia. |
| `data[].enabled` | boolean | no | false until the merchant turns it on, and back to false when the price or company name changes. |
| `data[].updated_at` | string (date-time) | no |  |
| `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/delivery-options" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "options": [ { "key": "one-hour", "company_name": "Fast Courier", "label": "Delivery within an hour", "eta": "Within an hour", "price": "25.00", "cities": [] } ] }'
```


## Example response (200)

```json
{
  "data": [
    {
      "key": "one-hour",
      "company_name": "Fast Courier",
      "label": "Delivery within an hour",
      "eta": "Within an hour",
      "price": "25.00",
      "cities": [],
      "enabled": false,
      "updated_at": "2026-11-02T09:00:00.000Z"
    }
  ],
  "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 |
|---|---|---|
| 422 | `INVALID_DELIVERY_OPTIONS` | Not a list, more than 10 options, a repeated or invalid key, or more than 50 cities. |
| 422 | `INVALID_PRICE` | The price is not a string from 0 to 1000 with up to two decimals. |
| 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. |