# Create a product

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `POST https://payme-store-staging.payme.io/api/products`
- Production: `POST https://payme-store.payme.io/api/products`

## Credentials

- Header `Authorization: Bearer <token>`

Adds a product to the seller's catalogue. `name`, `status` and `store_prices` are required. The response returns the new product's `guid`; use it with `/products/{guid}`.

The request names the price objects `store_prices` and `costs`; responses name them `store_configuration` and `costs_details`. Fields the API doesn't know are ignored.

Send `Authorization: Bearer <auth_token>`, the token from [`POST /auth-tokens`](/products-and-customers/authentication/post-auth-token). Hosts, tokens and the error format: [Hosts, authentication and errors](/products-and-customers/authentication). Prices are decimal amounts in major units (`99.99`), not minor units.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

The product to create.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_remote_id` | string | no | Your own product id, 2–100 characters, unique among the seller's products (`409` otherwise). |
| `name` | string | yes | Product name, 2–100 characters. |
| `status` | integer | yes | `1` – available, `0` – unavailable, `-1` – draft. |
| `description` | string | no | Product description, at least 2 characters. |
| `store_prices` | object | yes | Selling price. Returned as `store_configuration`. The `currency` and `price[min]`/`price[max]` filters of `GET /products` match its `price_include_vat`. |
| `store_prices.is_vat_free` | boolean | no | `true` if the product is exempt from VAT. |
| `store_prices.price_without_vat` | object | no | Price before VAT. |
| `store_prices.price_without_vat.amount` | number | yes | Decimal amount in major units, e.g. `99.99`. |
| `store_prices.price_without_vat.currency` | string | yes | ISO 4217 currency code, e.g. `ILS`. |
| `store_prices.price_include_vat` | object | no | Price including VAT. |
| `store_prices.price_include_vat.amount` | number | yes | Decimal amount in major units, e.g. `99.99`. |
| `store_prices.price_include_vat.currency` | string | yes | ISO 4217 currency code, e.g. `ILS`. |
| `costs` | object | no | Your cost for the product, same shape as `store_prices`. Returned as `costs_details`. |
| `costs.is_vat_free` | boolean | no | `true` if the product is exempt from VAT. |
| `costs.price_without_vat` | object | no | Price before VAT. |
| `costs.price_without_vat.amount` | number | yes | Decimal amount in major units, e.g. `99.99`. |
| `costs.price_without_vat.currency` | string | yes | ISO 4217 currency code, e.g. `ILS`. |
| `costs.price_include_vat` | object | no | Price including VAT. |
| `costs.price_include_vat.amount` | number | yes | Decimal amount in major units, e.g. `99.99`. |
| `costs.price_include_vat.currency` | string | yes | ISO 4217 currency code, e.g. `ILS`. |

### Request example

```json
{
  "product_remote_id": "PROD003",
  "name": "Detailed costs product",
  "status": 1,
  "description": "This product includes detailed cost information.",
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 150,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 177,
      "currency": "ILS"
    }
  },
  "costs": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 70,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 82.6,
      "currency": "ILS"
    }
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://payme-store-staging.payme.io/api/products' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "product_remote_id": "PROD003",
  "name": "Detailed costs product",
  "status": 1,
  "description": "This product includes detailed cost information.",
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 150,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 177,
      "currency": "ILS"
    }
  },
  "costs": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 70,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 82.6,
      "currency": "ILS"
    }
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/products", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "product_remote_id": "PROD003",
    "name": "Detailed costs product",
    "status": 1,
    "description": "This product includes detailed cost information.",
    "store_prices": {
      "is_vat_free": false,
      "price_without_vat": {
        "amount": 150,
        "currency": "ILS"
      },
      "price_include_vat": {
        "amount": 177,
        "currency": "ILS"
      }
    },
    "costs": {
      "is_vat_free": false,
      "price_without_vat": {
        "amount": 70,
        "currency": "ILS"
      },
      "price_include_vat": {
        "amount": 82.6,
        "currency": "ILS"
      }
    }
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://payme-store-staging.payme.io/api/products",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "product_remote_id": "PROD003",
        "name": "Detailed costs product",
        "status": 1,
        "description": "This product includes detailed cost information.",
        "store_prices": {
            "is_vat_free": False,
            "price_without_vat": {
                "amount": 150,
                "currency": "ILS",
            },
            "price_include_vat": {
                "amount": 177,
                "currency": "ILS",
            },
        },
        "costs": {
            "is_vat_free": False,
            "price_without_vat": {
                "amount": 70,
                "currency": "ILS",
            },
            "price_include_vat": {
                "amount": 82.6,
                "currency": "ILS",
            },
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "product_remote_id": "PROD003",
  "name": "Detailed costs product",
  "status": 1,
  "description": "This product includes detailed cost information.",
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 150,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 177,
      "currency": "ILS"
    }
  },
  "costs": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 70,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 82.6,
      "currency": "ILS"
    }
  }
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/products');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 201 — Product created. (success)

| Field | Type | Description |
| --- | --- | --- |
| `guid` | string | The new product's id (a UUID). Use it in `/products/{guid}`. |
| `created_at` | string | Creation time, ISO 8601 (UTC). |

```json
{
  "guid": "3f2b8f0e-5d7c-4a1e-9b8a-2c4d6e8f0a1b",
  "created_at": "2026-11-09T10:00:00.000Z"
}
```

### 400 — A required field is missing, a field is invalid, or the body isn't valid JSON. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. Validation messages are in Hebrew unless you send `Accept-Language: en`. |
| `status_error_code` | integer | `501` for a validation error or a body that isn't valid JSON, `999` for any other error. |
| `validation_errors` | object | The fields that failed validation. Each key is a field name; its value maps each failed rule to a message. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

```json
{
  "status_error_details": "Please verify that the JSON provided is valid",
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 401 — The `Authorization` header is missing, or the access token is invalid or expired. Get a new token with `POST /refresh-exchanges` or `POST /auth-tokens`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. |
| `status_error_code` | integer | `999`. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

```json
{
  "status_error_details": "Unauthorized",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 409 — `product_remote_id` is already used by another of the seller's products. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. |
| `status_error_code` | integer | `999`. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

```json
{
  "status_error_details": "Product remote id already exist",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 500 — Server error. Contact PayMe support and quote the `session`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. |
| `status_error_code` | integer | `999`. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |