# Products and Customers

## Authentication

- [Authentication](https://docs.payme.io/products-and-customers/authentication): Hosts: https://payme-store-staging.payme.io/api/ (sandbox), https://payme-store.payme.io/api/ (production). POST /auth-tokens with {"mpl": seller MPL, "key": partner payme_client_key} returns 201 with auth_token (JWT) and refresh_token; send Authorization: Bearer <auth_token>. POST /refresh-exchanges with {"refresh_token"} (no headers) returns a new auth_token and a new single-use refresh_token. Prices are decimal major units as {amount, currency}. Errors: status_error_details, status_error_code (501 validation, 999 other), validation_errors, session; HTTP 400, 401, 404, 409, 500.

# Authentication

## Related

- [Get an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-token)
- [Refresh an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-refresh)
- [Authentication](https://docs.payme.io/payments/getting-started/authentication)

Products & Customers keeps a seller's product catalogue and customer list. It is a separate PayMe service with its own access token: get a token for the seller, then send it as `Authorization: Bearer <auth_token>` on every product and customer call.

## Hosts

| Environment | Base URL |
|---|---|
| Sandbox (testing) | `https://payme-store-staging.payme.io/api/` |
| Production | `https://payme-store.payme.io/api/` |

These hosts are separate from the Payments API hosts (`sandbox.payme.io`, `live.payme.io`). Use sandbox credentials (the seller's sandbox MPL and your sandbox `payme_client_key`) with the sandbox host, and production credentials with the production host.

## Authentication

1. Call [`POST /auth-tokens`](https://docs.payme.io/products-and-customers/authentication/post-auth-token) with `{"mpl": "<seller MPL>", "key": "<partner payme_client_key>"}`. The seller must belong to the partner whose key you send. The call returns HTTP `201` with `auth_token` (a JWT) and `refresh_token`.
2. Send `Authorization: Bearer <auth_token>` on every product and customer call. A missing, invalid or expired token returns HTTP `401`.
3. When the access token expires, call [`POST /refresh-exchanges`](https://docs.payme.io/products-and-customers/authentication/post-auth-refresh) with `{"refresh_token": "<refresh_token>"}`. No headers are needed. It returns a new `auth_token` and a new `refresh_token`. Each refresh token works once, so store the new one. If the refresh token has expired or was already used, start again at step 1.



Only partners can get a token: `key` is the partner's `payme_client_key`, and a seller without a partner key can't call this API. What the MPL (`seller_payme_id`) and the partner key are: Payments [Authentication](https://docs.payme.io/payments/getting-started/authentication).

## Amounts

Prices in this API are decimal amounts in major units, sent as money objects such as `{"amount": 99.99, "currency": "ILS"}`. This differs from the Payments API, which uses minor units.

## Errors

Every error returns a JSON body with these fields:

| Field | Type | Description |
|---|---|---|
| `status_error_details` | string | What went wrong. Validation messages are in Hebrew unless you send `Accept-Language: en` (or add `?lang=en`). |
| `status_error_code` | integer | `501` – a field failed validation (HTTP `400`). `999` – any other error. |
| `validation_errors` | object | Validation errors only. Each key is a field name; its value maps each failed rule to a message. |
| `status_additional_info` | string | Extra detail, when there is any. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

| HTTP status | Meaning |
|---|---|
| `400` | Invalid input: a missing or invalid field, a body that isn't valid JSON, or a `guid` that isn't a UUID. |
| `401` | Missing, invalid or expired access token, or a refresh token that is unknown, used or expired. |
| `404` | The product or customer doesn't exist, was deleted, or belongs to another seller. |
| `409` | Another of the seller's products already uses that `product_remote_id`, or another customer that `customer_external_id`. |
| `500` | Server error. Contact PayMe support and quote the `session`. |

```json
{
  "status_error_details": "Field validation failed.",
  "validation_errors": {
    "items_per_page": {
      "max": "The value must be less than max amount."
    }
  },
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

- [Get an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-token): POST /auth-tokens — Get an access token

# Get an access token

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

## Credentials

No credentials are documented for this endpoint.

Exchanges a seller's MPL and its partner's `payme_client_key` for an access token and a refresh token. Send the access token as `Authorization: Bearer <auth_token>` on every product and customer call.

Only partners can get a token: the seller in `mpl` must belong to the partner whose key you send in `key`. When the access token expires, get a new pair with [`POST /refresh-exchanges`](/products-and-customers/authentication/post-auth-refresh).

Wrong or mismatched credentials return an error; read `status_error_details`. The HTTP status can be `400`, `401` or `500`, depending on how PayMe's core rejects the credentials.

Hosts and the error format: [Hosts, authentication and errors](/products-and-customers/authentication).

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

The seller and partner credentials.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mpl` | string | yes | The seller's MPL (`seller_payme_id`), e.g. `MPLDEMO-MPLDEMO-MPLDEMO-1234567`. The token acts for this seller. |
| `key` | string | yes | The partner's `payme_client_key`. The seller in `mpl` must belong to this partner. |

### Request example

```json
{
  "mpl": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "key": "your_payme_client_key"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://payme-store-staging.payme.io/api/auth-tokens' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "mpl": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "key": "your_payme_client_key"
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/auth-tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mpl": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "key": "your_payme_client_key"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://payme-store-staging.payme.io/api/auth-tokens",
    json={
        "mpl": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "key": "your_payme_client_key",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "mpl": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "key": "your_payme_client_key"
}
BODY;

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

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

echo $response;
```

## Responses

### 201 — Tokens issued. (success)

| Field | Type | Description |
| --- | --- | --- |
| `auth_token` | string | The access token, a JWT. Send it as `Authorization: Bearer <auth_token>` on product and customer calls. |
| `refresh_token` | string | A single-use token for `POST /refresh-exchanges`, which returns a new pair of tokens. |

```json
{
  "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzFlNGQ5YSJ9.c2lnbmF0dXJl",
  "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"
}
```

### 400 — `mpl` or `key` is missing or not a string, or the body isn't valid JSON. Wrong credentials can also return `400`. (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": "Field validation failed.",
  "validation_errors": {
    "key": {
      "is_not_empty": "The field is required.",
      "is_string": "The value must be a string."
    }
  },
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 401 — The credentials don't identify a seller of this partner. (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": "No Genesis identity found for the credentials",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 500 — Server error. Wrong credentials can also return `500`. 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. |

- [Refresh an access token](https://docs.payme.io/products-and-customers/authentication/post-auth-refresh): POST /refresh-exchanges — Refresh an access token

# Refresh an access token

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

## Credentials

- Header `PayMe-Partner-Key` (API key) and Header `PayMe-Merchant-Key` (API key)
- Request body field `refresh_token` (required): The `refresh_token` from your last `POST /auth-tokens` or `POST /refresh-exchanges` call. Each refresh token works once.

Exchanges a refresh token for a new access token and a new refresh token. The refresh token you send stops working, so store the new one.

The refresh token identifies the seller, so the call needs no `Authorization`, `PayMe-Partner-Key` or `PayMe-Merchant-Key` header. If the refresh token is unknown, already used or expired, start again with [`POST /auth-tokens`](/products-and-customers/authentication/post-auth-token).

Hosts and the error format: [Hosts, authentication and errors](/products-and-customers/authentication).

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

The refresh token to exchange.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refresh_token` | string | yes | The `refresh_token` from your last `POST /auth-tokens` or `POST /refresh-exchanges` call. Each refresh token works once. |

### Request example

```json
{
  "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://payme-store-staging.payme.io/api/refresh-exchanges' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Partner-Key: <YOUR_API_KEY>' \
  -H 'PayMe-Merchant-Key: <YOUR_API_KEY>' \
  --data-raw '{
  "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/refresh-exchanges", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Partner-Key": "<YOUR_API_KEY>",
    "PayMe-Merchant-Key": "<YOUR_API_KEY>",
  },
  body: JSON.stringify({
    "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://payme-store-staging.payme.io/api/refresh-exchanges",
    headers={
        "PayMe-Partner-Key": "<YOUR_API_KEY>",
        "PayMe-Merchant-Key": "<YOUR_API_KEY>",
    },
    json={
        "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "refresh_token": "b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/refresh-exchanges');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Partner-Key: <YOUR_API_KEY>',
        'PayMe-Merchant-Key: <YOUR_API_KEY>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 201 — New tokens issued. The refresh token you sent no longer works. (success)

| Field | Type | Description |
| --- | --- | --- |
| `auth_token` | string | The access token, a JWT. Send it as `Authorization: Bearer <auth_token>` on product and customer calls. |
| `refresh_token` | string | A single-use token for `POST /refresh-exchanges`, which returns a new pair of tokens. |

```json
{
  "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ZDJiNmYxMCJ9.c2lnbmF0dXJl",
  "refresh_token": "0e7c4b19-2d6a-4f83-b5e1-7a9c3d2f8b64"
}
```

### 400 — `refresh_token` is missing or not a string, 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": "Field validation failed.",
  "validation_errors": {
    "refresh_token": {
      "is_not_empty": "The field is required.",
      "is_string": "The value must be a string."
    }
  },
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 401 — The refresh token is unknown, already used or expired. Get a new pair with `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"
}
```

### 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. |


## Products

- [List products](https://docs.payme.io/products-and-customers/products/get-products): GET /products — List products

# List products

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

## Credentials

- Header `Authorization: Bearer <token>`

Lists the seller's products, one page at a time. `page` and `items_per_page` are required. Filter by status, text, your own product id, store currency, store price or creation date, and sort by name, status or creation date. Without `sort_by` the order isn't defined.

Pass the range filters in deep-object form, e.g. `?price[min]=10&price[max]=200&created_at[from]=2026-01-01`.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | yes | Page number, from `1`. |
| `items_per_page` | query | integer | yes | Products per page, from `1` to `100`. |
| `status` | query | integer | no | `1` – available, `0` – unavailable, `-1` – draft. |
| `search` | query | string | no | Case-insensitive text to find in the name or the description. |
| `name` | query | string | no | Case-insensitive text to find in the name, 2–100 characters. |
| `description` | query | string | no | Case-insensitive text to find in the description, 2–100 characters. |
| `product_remote_id` | query | string | no | Your own product id, exact match. |
| `currency` | query | string | no | ISO 4217 code (e.g. `ILS`) of the store price including VAT. |
| `price[min]` | query | number | no | Lowest store price including VAT, in major units. |
| `price[max]` | query | number | no | Highest store price including VAT, in major units. |
| `created_at[from]` | query | string | no | Created at or after this time: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. |
| `created_at[to]` | query | string | no | Created at or before this time, in the same formats. |
| `sort_by` | query | string | no | `name`, `status` or `created_at`. |
| `sort_direction` | query | string | no | `asc` or `desc`. Default `desc`. Applies only together with `sort_by`. |

## Code samples

### curl

```bash
curl -X GET 'https://payme-store-staging.payme.io/api/products?page=<page>&items_per_page=<items_per_page>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/products?page=<page>&items_per_page=<items_per_page>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://payme-store-staging.payme.io/api/products?page=<page>&items_per_page=<items_per_page>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/products?page=<page>&items_per_page=<items_per_page>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — A page of products. (success)

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | The products on this page. |
| `items[].guid` | string | Product id (a UUID) assigned by PayMe. Use it in `/products/{guid}`. |
| `items[].product_remote_id` | string | Your own product id. Left out when not set. |
| `items[].name` | string | Product name. |
| `items[].status` | integer | `1` – available, `0` – unavailable, `-1` – draft. |
| `items[].description` | string | Product description. |
| `items[].store_configuration` | object | Selling price. You send it as `store_prices` when you create or update the product. The `currency` and `price[min]`/`price[max]` filters of `GET /products` match its `price_include_vat`. |
| `items[].store_configuration.is_vat_free` | boolean | `true` if the product is exempt from VAT. |
| `items[].store_configuration.price_without_vat` | object | Price before VAT. `null` when not set. |
| `items[].store_configuration.price_without_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `items[].store_configuration.price_without_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `items[].store_configuration.price_include_vat` | object | Price including VAT. `null` when not set. |
| `items[].store_configuration.price_include_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `items[].store_configuration.price_include_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `items[].costs_details` | object | Your cost for the product, same shape as `store_configuration`. You send it as `costs`. Left out when not set. |
| `items[].costs_details.is_vat_free` | boolean | `true` if the product is exempt from VAT. |
| `items[].costs_details.price_without_vat` | object | Price before VAT. `null` when not set. |
| `items[].costs_details.price_without_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `items[].costs_details.price_without_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `items[].costs_details.price_include_vat` | object | Price including VAT. `null` when not set. |
| `items[].costs_details.price_include_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `items[].costs_details.price_include_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `total` | integer | How many products match the filters, across all pages. |
| `page` | integer | The page returned. |
| `items_per_page` | integer | The page size you asked for. |

```json
{
  "items": [
    {
      "guid": "3f2b8f0e-5d7c-4a1e-9b8a-2c4d6e8f0a1b",
      "product_remote_id": "PROD001",
      "name": "Example product",
      "status": 1,
      "description": "Example description",
      "store_configuration": {
        "is_vat_free": false,
        "price_without_vat": {
          "amount": 99.99,
          "currency": "ILS"
        },
        "price_include_vat": {
          "amount": 117.99,
          "currency": "ILS"
        }
      },
      "costs_details": {
        "is_vat_free": false,
        "price_without_vat": {
          "amount": 50,
          "currency": "ILS"
        },
        "price_include_vat": {
          "amount": 59,
          "currency": "ILS"
        }
      }
    }
  ],
  "total": 1,
  "page": 1,
  "items_per_page": 20
}
```

### 400 — A required parameter is missing or a parameter is invalid, e.g. `items_per_page` above `100`. (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": "Field validation failed.",
  "validation_errors": {
    "items_per_page": {
      "max": "The value must be less than max amount."
    }
  },
  "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"
}
```

### 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. |

- [Get a product](https://docs.payme.io/products-and-customers/products/get-products-guid): GET /products/{guid} — Get a product

# Get a product

- Sandbox: `GET https://payme-store-staging.payme.io/api/products/{guid}`
- Production: `GET https://payme-store.payme.io/api/products/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Returns one of the seller's products by its `guid`. A product that doesn't exist, was deleted or belongs to another seller returns `404`.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The product `guid` (a UUID) that `POST /products` returned. Any other format returns `400`. |

## Code samples

### curl

```bash
curl -X GET 'https://payme-store-staging.payme.io/api/products/<guid>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/products/<guid>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://payme-store-staging.payme.io/api/products/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/products/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — The product. (success)

| Field | Type | Description |
| --- | --- | --- |
| `guid` | string | Product id (a UUID) assigned by PayMe. Use it in `/products/{guid}`. |
| `product_remote_id` | string | Your own product id. Left out when not set. |
| `name` | string | Product name. |
| `status` | integer | `1` – available, `0` – unavailable, `-1` – draft. |
| `description` | string | Product description. |
| `store_configuration` | object | Selling price. You send it as `store_prices` when you create or update the product. The `currency` and `price[min]`/`price[max]` filters of `GET /products` match its `price_include_vat`. |
| `store_configuration.is_vat_free` | boolean | `true` if the product is exempt from VAT. |
| `store_configuration.price_without_vat` | object | Price before VAT. `null` when not set. |
| `store_configuration.price_without_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `store_configuration.price_without_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `store_configuration.price_include_vat` | object | Price including VAT. `null` when not set. |
| `store_configuration.price_include_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `store_configuration.price_include_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `costs_details` | object | Your cost for the product, same shape as `store_configuration`. You send it as `costs`. Left out when not set. |
| `costs_details.is_vat_free` | boolean | `true` if the product is exempt from VAT. |
| `costs_details.price_without_vat` | object | Price before VAT. `null` when not set. |
| `costs_details.price_without_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `costs_details.price_without_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `costs_details.price_include_vat` | object | Price including VAT. `null` when not set. |
| `costs_details.price_include_vat.amount` | number | Decimal amount in major units, e.g. `99.99`. |
| `costs_details.price_include_vat.currency` | string | ISO 4217 currency code, e.g. `ILS`. |

```json
{
  "guid": "3f2b8f0e-5d7c-4a1e-9b8a-2c4d6e8f0a1b",
  "product_remote_id": "PROD001",
  "name": "Example product",
  "status": 1,
  "description": "Example description",
  "store_configuration": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 99.99,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 117.99,
      "currency": "ILS"
    }
  },
  "costs_details": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 50,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 59,
      "currency": "ILS"
    }
  }
}
```

### 400 — `guid` isn't a UUID. (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": "Validation failed (uuid is expected)",
  "status_error_code": 999,
  "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"
}
```

### 404 — The product doesn't exist, was deleted, or belongs to another seller. (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 not found",
  "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. |

- [Update a product](https://docs.payme.io/products-and-customers/products/patch-products-product-id): PATCH /products/{guid} — Update a product

# Update a product

- Sandbox: `PATCH https://payme-store-staging.payme.io/api/products/{guid}`
- Production: `PATCH https://payme-store.payme.io/api/products/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Changes some fields of one of the seller's products. Fields you don't send keep their values. A price object you send (`store_prices` or `costs`) replaces the stored one entirely.

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.

To replace the whole product in one call, `PUT /products/{guid}` takes the same body as [`POST /products`](/products-and-customers/products/post-user), with the same required fields.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The product `guid` (a UUID) that `POST /products` returned. Any other format returns `400`. |

## Request body

Content type: `application/json`

The fields to change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_remote_id` | string | no | Your own product id, 2–100 characters, unique among the seller's products (`409` otherwise). Send it only to change it: resending the product's current value also returns `409`. |
| `name` | string | no | Product name, 2–100 characters. |
| `status` | integer | no | `1` – available, `0` – unavailable, `-1` – draft. |
| `description` | string | no | Product description, at least 2 characters. |
| `store_prices` | object | no | Selling price. Replaces the stored selling price entirely: send `is_vat_free` and both prices together. 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`. Replaces the stored cost entirely. 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
{
  "name": "Example product",
  "status": 1,
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 99.99,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 117.99,
      "currency": "ILS"
    }
  }
}
```

## Code samples

### curl

```bash
curl -X PATCH 'https://payme-store-staging.payme.io/api/products/<guid>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "name": "Example product",
  "status": 1,
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 99.99,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 117.99,
      "currency": "ILS"
    }
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/products/<guid>", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "name": "Example product",
    "status": 1,
    "store_prices": {
      "is_vat_free": false,
      "price_without_vat": {
        "amount": 99.99,
        "currency": "ILS"
      },
      "price_include_vat": {
        "amount": 117.99,
        "currency": "ILS"
      }
    }
  }),
});

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

### Python

```python
import requests

response = requests.patch(
    "https://payme-store-staging.payme.io/api/products/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "name": "Example product",
        "status": 1,
        "store_prices": {
            "is_vat_free": False,
            "price_without_vat": {
                "amount": 99.99,
                "currency": "ILS",
            },
            "price_include_vat": {
                "amount": 117.99,
                "currency": "ILS",
            },
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "name": "Example product",
  "status": 1,
  "store_prices": {
    "is_vat_free": false,
    "price_without_vat": {
      "amount": 99.99,
      "currency": "ILS"
    },
    "price_include_vat": {
      "amount": 117.99,
      "currency": "ILS"
    }
  }
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/products/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    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

### 200 — Product updated. (success)

| Field | Type | Description |
| --- | --- | --- |
| `guid` | string | The product id (a UUID). |
| `created_at` | string | Creation time, ISO 8601 (UTC). |
| `updated_at` | string | Time of this update, ISO 8601 (UTC). |

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

### 400 — A field is invalid, the body isn't valid JSON, or `guid` isn't a UUID. (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"
}
```

### 404 — The product doesn't exist, was deleted, or belongs to another seller. (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 not found",
  "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. |

- [Delete a product](https://docs.payme.io/products-and-customers/products/delete-products-guid): DELETE /products/{guid} — Delete a product

# Delete a product

- Sandbox: `DELETE https://payme-store-staging.payme.io/api/products/{guid}`
- Production: `DELETE https://payme-store.payme.io/api/products/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Deletes one of the seller's products. Deleted products no longer appear in lists or reads, and their `guid` returns `404`. The call has no request body and returns `204 No Content`.

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).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The product `guid` (a UUID) that `POST /products` returned. Any other format returns `400`. |

## Code samples

### curl

```bash
curl -X DELETE 'https://payme-store-staging.payme.io/api/products/<guid>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/products/<guid>", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.delete(
    "https://payme-store-staging.payme.io/api/products/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/products/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 204 — Product deleted. The response has no body. (success)

### 400 — `guid` isn't a UUID. (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": "Validation failed (uuid is expected)",
  "status_error_code": 999,
  "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"
}
```

### 404 — The product doesn't exist, was deleted, or belongs to another seller. (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 not found",
  "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. |

- [Create a product](https://docs.payme.io/products-and-customers/products/post-user): POST /products — Create a product

# Create a product

- 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. |


## Customers

- [List customers](https://docs.payme.io/products-and-customers/customers/get-customers): GET /customers — List customers

# List customers

- Sandbox: `GET https://payme-store-staging.payme.io/api/customers`
- Production: `GET https://payme-store.payme.io/api/customers`

## Credentials

- Header `Authorization: Bearer <token>`

Lists the seller's customers, one page at a time. `page` and `items_per_page` are required. Filter by status, name, email, phone or creation date, or search across the names, the email and the `guid`. Sort by first name, last name, email or creation date; without `sort_by` the order isn't defined.

Pass the date range in deep-object form, e.g. `?created_at[from]=2026-01-01&created_at[to]=2026-06-30`.

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).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | yes | Page number, from `1`. |
| `items_per_page` | query | integer | yes | Customers per page, from `1` to `100`. |
| `status` | query | integer | no | `0` – inactive, `1` – active, `2` – draft. |
| `search` | query | string | no | Case-insensitive text to find in the first, middle or last name, the full name, the `guid` or the email. |
| `first_name` | query | string | no | First name, exact match. |
| `last_name` | query | string | no | Last name, exact match. |
| `email` | query | string | no | Email address, exact match. |
| `mobile_number` | query | string | no | Phone number, exact match against the main or the additional phone. |
| `created_at[from]` | query | string | no | Created at or after this time: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. |
| `created_at[to]` | query | string | no | Created at or before this time, in the same formats. |
| `sort_by` | query | string | no | `first_name`, `last_name`, `email` or `created_at`. |
| `sort_direction` | query | string | no | `asc` or `desc`. Default `desc`. Applies only together with `sort_by`. |

## Code samples

### curl

```bash
curl -X GET 'https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — A page of customers. (success)

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | The customers on this page. |
| `items[].guid` | string | Customer id (a UUID) assigned by PayMe. Use it in `/customers/{guid}`. |
| `items[].first_name` | string | First name. |
| `items[].middle_name` | string | Middle name. |
| `items[].last_name` | string | Last name. |
| `items[].email` | string | Email address. |
| `items[].phone_number` | string | Main phone number. You send it as `phone`. |
| `items[].additional_phone_number` | string | Second phone number. You send it as `additional_phone`. |
| `items[].address` | object | Postal address. You send these fields at the top level of the request. |
| `items[].address.country` | string | Country. |
| `items[].address.city` | string | City. |
| `items[].address.street` | string | Street. |
| `items[].address.building_number` | string | Building number, e.g. `12A`. |
| `items[].address.floor` | string | Floor. |
| `items[].address.zip` | string | Postal code. |
| `items[].company_name` | string | Company name. |
| `items[].description` | string | Your note about the customer. |
| `items[].birthday` | string | Date of birth, `YYYY-MM-DD`. |
| `items[].status` | integer | `0` – inactive, `1` – active, `2` – draft. |
| `items[].payment_tokens` | array | The customer's saved payment tokens. |
| `items[].payment_tokens[].token` | string | A payment token you saved for the customer. |
| `items[].payment_tokens[].token_data` | string | The JSON string you saved with the token, e.g. the card mask and brand. |
| `total` | integer | How many customers match the filters, across all pages. |
| `page` | integer | The page returned. |
| `items_per_page` | integer | The page size you asked for. |

```json
{
  "items": [
    {
      "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "first_name": "Dana",
      "middle_name": null,
      "last_name": "Levi",
      "email": "dana@example.com",
      "phone_number": "0501234567",
      "additional_phone_number": null,
      "address": {
        "country": "Israel",
        "city": "Tel Aviv",
        "street": "Rothschild",
        "building_number": "12A",
        "floor": "3",
        "zip": "6688101"
      },
      "company_name": "Example Ltd",
      "description": "Prefers email contact",
      "birthday": "1990-05-17",
      "status": 1,
      "payment_tokens": [
        {
          "token": "8f3a2c1d9e7b4a60",
          "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "items_per_page": 20
}
```

### 400 — A required parameter is missing or a parameter is invalid, e.g. `items_per_page` above `100`. (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": "Field validation failed.",
  "validation_errors": {
    "items_per_page": {
      "max": "The value must be less than max amount."
    }
  },
  "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"
}
```

### 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. |

- [Create a customer](https://docs.payme.io/products-and-customers/customers/post-customers): POST /customers — Create a customer

# Create a customer

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

## Credentials

- Header `Authorization: Bearer <token>`

Adds a customer to the seller's customer list. `first_name`, `last_name`, `email`, `phone` and `status` are required. The response returns the new customer's `guid`; use it with `/customers/{guid}`.

The request names the phone fields `phone` and `additional_phone` and sends the address fields at the top level; responses name them `phone_number` and `additional_phone_number` and nest the address in `address`. 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).

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

The customer to create.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_external_id` | string | no | Your own customer id, unique among the seller's customers (`409` otherwise). It isn't returned when you read the customer. |
| `first_name` | string | yes | First name, at least 2 characters. |
| `middle_name` | string | no | Middle name, at least 2 characters. |
| `last_name` | string | yes | Last name, at least 2 characters. |
| `email` | string | yes | A valid email address. |
| `phone` | string | yes | Main phone number, 3–20 characters. Returned as `phone_number`. |
| `additional_phone` | string | no | Second phone number, 3–20 characters. Returned as `additional_phone_number`. |
| `company_name` | string | no | Company name, at least 2 characters. |
| `country` | string | no | Country, at least 2 characters. Returned inside `address`. |
| `city` | string | no | City, at least 2 characters. Returned inside `address`. |
| `street` | string | no | Street, at least 2 characters. Returned inside `address`. |
| `building_number` | string | no | Building number, e.g. `12` or `12A`. Returned inside `address`. |
| `floor` | string | no | Floor, at least 1 character. Returned inside `address`. |
| `zip` | string | no | Postal code. Returned inside `address`. |
| `description` | string | no | Your note about the customer. |
| `birthday` | string | no | Date of birth, `YYYY-MM-DD`. |
| `status` | integer | yes | `0` – inactive, `1` – active, `2` – draft. |
| `payment_tokens` | array | no | Payment tokens to save for the customer. |
| `payment_tokens[].token` | string | yes | The payment token to save. PayMe stores it as given. |
| `payment_tokens[].token_data` | string | no | A JSON object encoded as a string, e.g. the card mask and brand: `{"card_mask":"4580 **** **** 0000","card_brand":"visa"}`. Must be valid JSON. |

### Request example

```json
{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}
```

## Code samples

### curl

```bash
curl -X POST 'https://payme-store-staging.payme.io/api/customers' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "customer_external_id": "CUST-1001",
    "first_name": "Dana",
    "last_name": "Levi",
    "email": "dana@example.com",
    "phone": "0501234567",
    "status": 1,
    "country": "Israel",
    "city": "Tel Aviv",
    "street": "Rothschild",
    "building_number": "12A",
    "birthday": "1990-05-17",
    "payment_tokens": [
      {
        "token": "8f3a2c1d9e7b4a60",
        "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
      }
    ]
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://payme-store-staging.payme.io/api/customers",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "customer_external_id": "CUST-1001",
        "first_name": "Dana",
        "last_name": "Levi",
        "email": "dana@example.com",
        "phone": "0501234567",
        "status": 1,
        "country": "Israel",
        "city": "Tel Aviv",
        "street": "Rothschild",
        "building_number": "12A",
        "birthday": "1990-05-17",
        "payment_tokens": [
            {
                "token": "8f3a2c1d9e7b4a60",
                "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}",
            },
        ],
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/customers');
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 — Customer created. (success)

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

```json
{
  "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "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": "Field validation failed.",
  "validation_errors": {
    "email": {
      "is_email": "The value must be a valid email address."
    }
  },
  "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 — `customer_external_id` is already used by another of the seller's customers. (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": "Customer external 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. |

- [Get a customer](https://docs.payme.io/products-and-customers/customers/get-customers-guid): GET /customers/{guid} — Get a customer

# Get a customer

- Sandbox: `GET https://payme-store-staging.payme.io/api/customers/{guid}`
- Production: `GET https://payme-store.payme.io/api/customers/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Returns one of the seller's customers by its `guid`. A customer that doesn't exist, was deleted or belongs to another seller returns `404`.

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).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The customer `guid` (a UUID) that `POST /customers` returned. Any other format returns `400`. |

## Code samples

### curl

```bash
curl -X GET 'https://payme-store-staging.payme.io/api/customers/<guid>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers/<guid>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://payme-store-staging.payme.io/api/customers/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/customers/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — The customer. (success)

| Field | Type | Description |
| --- | --- | --- |
| `guid` | string | Customer id (a UUID) assigned by PayMe. Use it in `/customers/{guid}`. |
| `first_name` | string | First name. |
| `middle_name` | string | Middle name. |
| `last_name` | string | Last name. |
| `email` | string | Email address. |
| `phone_number` | string | Main phone number. You send it as `phone`. |
| `additional_phone_number` | string | Second phone number. You send it as `additional_phone`. |
| `address` | object | Postal address. You send these fields at the top level of the request. |
| `address.country` | string | Country. |
| `address.city` | string | City. |
| `address.street` | string | Street. |
| `address.building_number` | string | Building number, e.g. `12A`. |
| `address.floor` | string | Floor. |
| `address.zip` | string | Postal code. |
| `company_name` | string | Company name. |
| `description` | string | Your note about the customer. |
| `birthday` | string | Date of birth, `YYYY-MM-DD`. |
| `status` | integer | `0` – inactive, `1` – active, `2` – draft. |
| `payment_tokens` | array | The customer's saved payment tokens. |
| `payment_tokens[].token` | string | A payment token you saved for the customer. |
| `payment_tokens[].token_data` | string | The JSON string you saved with the token, e.g. the card mask and brand. |

```json
{
  "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "first_name": "Dana",
  "middle_name": null,
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone_number": "0501234567",
  "additional_phone_number": null,
  "address": {
    "country": "Israel",
    "city": "Tel Aviv",
    "street": "Rothschild",
    "building_number": "12A",
    "floor": "3",
    "zip": "6688101"
  },
  "company_name": "Example Ltd",
  "description": "Prefers email contact",
  "birthday": "1990-05-17",
  "status": 1,
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}
```

### 400 — `guid` isn't a UUID. (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": "Validation failed (uuid is expected)",
  "status_error_code": 999,
  "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"
}
```

### 404 — The customer doesn't exist, was deleted, or belongs to another seller. (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": "Customer not found",
  "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. |

- [Update a customer](https://docs.payme.io/products-and-customers/customers/patch-customers): PATCH /customers/{guid} — Update a customer

# Update a customer

- Sandbox: `PATCH https://payme-store-staging.payme.io/api/customers/{guid}`
- Production: `PATCH https://payme-store.payme.io/api/customers/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Changes some fields of one of the seller's customers. Fields you don't send, or send empty, keep their values. A `payment_tokens` array you send replaces all of the customer's saved tokens.

The request names the phone fields `phone` and `additional_phone` and sends the address fields at the top level; responses name them `phone_number` and `additional_phone_number` and nest the address in `address`. Fields the API doesn't know are ignored.

To replace the whole customer in one call, `PUT /customers/{guid}` takes the same body as [`POST /customers`](/products-and-customers/customers/post-customers), with the same required fields.

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).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The customer `guid` (a UUID) that `POST /customers` returned. Any other format returns `400`. |

## Request body

Content type: `application/json`

The fields to change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_external_id` | string | no | Your own customer id, unique among the seller's customers (`409` otherwise). It isn't returned when you read the customer. Send it only to change it: resending the customer's current value also returns `409`. |
| `first_name` | string | no | First name, at least 2 characters. |
| `middle_name` | string | no | Middle name, at least 2 characters. |
| `last_name` | string | no | Last name, at least 2 characters. |
| `email` | string | no | A valid email address. |
| `phone` | string | no | Main phone number, 3–20 characters. Returned as `phone_number`. |
| `additional_phone` | string | no | Second phone number, 3–20 characters. Returned as `additional_phone_number`. |
| `company_name` | string | no | Company name, at least 2 characters. |
| `country` | string | no | Country, at least 2 characters. Returned inside `address`. |
| `city` | string | no | City, at least 2 characters. Returned inside `address`. |
| `street` | string | no | Street, at least 2 characters. Returned inside `address`. |
| `building_number` | string | no | Building number, e.g. `12` or `12A`. Returned inside `address`. |
| `floor` | string | no | Floor, at least 1 character. Returned inside `address`. |
| `zip` | string | no | Postal code. Returned inside `address`. |
| `description` | string | no | Your note about the customer. |
| `status` | integer | no | `1` – active, `2` – draft. This call can't set `0` (inactive). |
| `payment_tokens` | array | no | Payment tokens to save for the customer. The array replaces all of the customer's saved tokens. |
| `payment_tokens[].token` | string | yes | The payment token to save. PayMe stores it as given. |
| `payment_tokens[].token_data` | string | no | A JSON object encoded as a string, e.g. the card mask and brand: `{"card_mask":"4580 **** **** 0000","card_brand":"visa"}`. Must be valid JSON. |

### Request example

```json
{
  "email": "dana.levi@example.com",
  "phone": "0527654321",
  "city": "Haifa"
}
```

## Code samples

### curl

```bash
curl -X PATCH 'https://payme-store-staging.payme.io/api/customers/<guid>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "email": "dana.levi@example.com",
  "phone": "0527654321",
  "city": "Haifa"
}'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers/<guid>", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "email": "dana.levi@example.com",
    "phone": "0527654321",
    "city": "Haifa"
  }),
});

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

### Python

```python
import requests

response = requests.patch(
    "https://payme-store-staging.payme.io/api/customers/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "email": "dana.levi@example.com",
        "phone": "0527654321",
        "city": "Haifa",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "email": "dana.levi@example.com",
  "phone": "0527654321",
  "city": "Haifa"
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/customers/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    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

### 200 — Customer updated. (success)

| Field | Type | Description |
| --- | --- | --- |
| `guid` | string | The customer id (a UUID). |
| `created_at` | string | Creation time, ISO 8601 (UTC). |
| `updated_at` | string | Time of this update, ISO 8601 (UTC). |

```json
{
  "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "created_at": "2026-11-01T09:30:00.000Z",
  "updated_at": "2026-11-09T10:00:00.000Z"
}
```

### 400 — A field is invalid, the body isn't valid JSON, or `guid` isn't a UUID. (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": "Field validation failed.",
  "validation_errors": {
    "email": {
      "is_email": "The value must be a valid email address."
    }
  },
  "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"
}
```

### 404 — The customer doesn't exist, was deleted, or belongs to another seller. (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": "Customer not found",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 409 — `customer_external_id` is already used by another of the seller's customers. (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": "Customer external 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. |

- [Delete a customer](https://docs.payme.io/products-and-customers/customers/delete-customers): DELETE /customers/{guid} — Delete a customer

# Delete a customer

- Sandbox: `DELETE https://payme-store-staging.payme.io/api/customers/{guid}`
- Production: `DELETE https://payme-store.payme.io/api/customers/{guid}`

## Credentials

- Header `Authorization: Bearer <token>`

Deletes one of the seller's customers. Deleted customers no longer appear in lists or reads, and their `guid` returns `404`. The call has no request body and returns `204 No Content`.

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).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `guid` | path | string | yes | The customer `guid` (a UUID) that `POST /customers` returned. Any other format returns `400`. |

## Code samples

### curl

```bash
curl -X DELETE 'https://payme-store-staging.payme.io/api/customers/<guid>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers/<guid>", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.delete(
    "https://payme-store-staging.payme.io/api/customers/<guid>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/customers/<guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 204 — Customer deleted. The response has no body. (success)

### 400 — `guid` isn't a UUID. (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": "Validation failed (uuid is expected)",
  "status_error_code": 999,
  "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"
}
```

### 404 — The customer doesn't exist, was deleted, or belongs to another seller. (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": "Customer not found",
  "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. |