# Create a coupon

Creates a discount coupon with its code, value and rules.

```http
POST https://larm.sa/stores/{storeId}/v1/coupons
```

Scope: `coupons:write`

`code` is up to 64 characters and is saved in capitals. `value` is a number: a percentage from 0 to 100 when `type` is `percent` (the default), or an amount in SAR when `type` is `fixed`. `scope` limits the coupon to the `category` or `product` IDs in `scope_ids`. `discounted_policy` decides what happens on discounted products: `all` applies, `exclude` skips them, and `block` refuses the coupon with them. See [Marketing and customer messages](/guides/messaging).

## Headers

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


## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes |  |
| `name` | string \| null | no |  |
| `value` | number | yes | The percentage from 0 to 100, or the amount in SAR. |
| `type` | string | no | One of: `percent`, `fixed`. |
| `active` | boolean | no |  |
| `start_date` | string \| null (date) | no |  |
| `expiry` | string \| null (date) | no | The last day the coupon works. |
| `usage_limit` | integer \| null | no |  |
| `scope` | string | no | One of: `all`, `category`, `product`. |
| `scope_ids` | array<integer> | no |  |
| `discounted_policy` | string | no | On discounted products: all applies, exclude skips them, block refuses the coupon with them. One of: `all`, `exclude`, `block`. |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.id` | string | no |  |
| `data.code` | string | no |  |
| `data.name` | string \| null | no |  |
| `data.type` | string | no | One of: `percent`, `fixed`. |
| `data.value` | string | no | Discount percentage or amount. |
| `data.usage` | integer | no | Number of uses. |
| `data.usage_limit` | integer \| null | no |  |
| `data.start_date` | string \| null (date) | no |  |
| `data.expiry` | string \| null (date) | no |  |
| `data.active` | boolean | no |  |
| `data.scope` | string | no | One of: `all`, `category`, `product`. |
| `data.scope_ids` | array \| null | no |  |
| `data.discounted_policy` | string | no | One of: `all`, `exclude`, `block`. |
| `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/coupons" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $UUID" \
  -H "Content-Type: application/json" \
  -d '{ "code": "welcome10", "name": "Welcome offer", "value": 10, "type": "percent", "expiry": "2026-12-31" }'
```


## Example response (200)

```json
{
  "data": {
    "id": "9",
    "code": "WELCOME10",
    "name": "Welcome offer",
    "type": "percent",
    "value": "10.00",
    "usage": 41,
    "usage_limit": null,
    "start_date": null,
    "expiry": "2026-12-31",
    "active": true,
    "scope": "all",
    "scope_ids": null,
    "discounted_policy": "all",
    "resource_version": 0
  },
  "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. |
| 409 | `STORE_RULE_REFUSED` | A store rule refused the command. Read the resource before you try again. |
| 422 | `INVALID_INPUT` | The store refused a value. Check the limits on this page. |
| 422 | `UNKNOWN_FIELD` | Unknown field. |
| 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. |