# Create a product

Creates a hidden product. It appears in the store once its price is set and it is activated.

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

Scope: `products:write`

A new product has `status: inactive`, price `0.00` and `price_state: required`. Sending `price` in the body also requires `products.prices:write`.

## Headers

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


## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `description` | string | no |  |
| `short_desc` | string | no |  |
| `image` | string \| null | no |  |
| `images` | array<string> | no |  |
| `image_alt` | string | no |  |
| `category` | string \| null | no |  |
| `slug` | string | no |  |
| `keywords` | array<string> | no |  |
| `supported_devices` | array<string> | no |  |
| `seo_title` | string | no |  |
| `seo_description` | string | no |  |
| `og_image` | string \| null | no |  |
| `product_kind` | string | yes | One of: `digital`, `service`, `physical`. |
| `price` | string | no |  |
| `old_price` | string \| null | no |  |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.id` | integer | no |  |
| `data.name` | string | no |  |
| `data.description` | string | no |  |
| `data.short_desc` | string \| null | no |  |
| `data.image` | string \| null | no |  |
| `data.images` | array<string> | no |  |
| `data.image_alt` | string \| null | no |  |
| `data.category` | string \| null | no | Category name. |
| `data.slug` | string \| null | no |  |
| `data.keywords` | array<string> | no |  |
| `data.supported_devices` | object | no |  |
| `data.seo_title` | string \| null | no |  |
| `data.seo_description` | string \| null | no |  |
| `data.og_image` | string \| null | no |  |
| `data.product_kind` | object | no | One of: `digital`, `service`, `physical`. |
| `data.status` | object | no | One of: `active`, `inactive`. |
| `data.price` | string | no | Price in SAR. |
| `data.old_price` | string \| null | no | Price before discount. |
| `data.price_state` | object | no | required until a price is set; a new product is created inactive with price 0.00. One of: `required`, `ready`. |
| `data.resource_version` | integer | 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/products" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $UUID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Top-up card 200 SAR", "description": "A 200 SAR balance top-up card.", "product_kind": "digital", "category": "Top-up cards" }'
```


## Example response (200)

```json
{
  "data": {
    "id": 312,
    "name": "Top-up card 200 SAR",
    "description": "A 100 SAR balance top-up card, delivered instantly after payment.",
    "short_desc": "Delivered instantly after payment",
    "image": "https://cdn.example/p/311.webp",
    "images": [
      "https://cdn.example/p/311-2.webp"
    ],
    "image_alt": "Top-up card",
    "category": "Top-up cards",
    "slug": "charge-100",
    "keywords": [
      "top-up",
      "balance"
    ],
    "supported_devices": null,
    "seo_title": "Top-up card 100 SAR",
    "seo_description": "Buy a top-up card and get the code instantly.",
    "og_image": null,
    "product_kind": "digital",
    "status": "inactive",
    "price": "0.00",
    "old_price": null,
    "price_state": "required",
    "resource_version": 1
  },
  "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. |
| 422 | `CATEGORY_NOT_FOUND` | The category does not exist. |
| 422 | `UNKNOWN_FIELD` | Unknown field. |