> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Store settings

> Configure your store's currency, taxes, language, and product availability.

Lets you configure the currency, tax rate, language, and other global settings for your store. You can send one or more fields in the same request.

<ParamField path="app_id" type="string" required>
  Your store ID in Jelou Shop.
</ParamField>

<ParamField body="currency" type="string">
  Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format (exactly 3 characters). Example: `USD`, `EUR`, `COP`, `MXN`.
</ParamField>

<ParamField body="tax_value" type="number">
  Tax rate as a decimal value between `0` and `1`. Example: `0.15` for 15%, `0.19` for 19%.
</ParamField>

<ParamField body="enable_per_product_tax" type="boolean">
  Enables individual tax rate configuration per product. When active, each product can have its own rate in the `tax` field. If the product does not have a rate configured, `tax_value` is used as a fallback.
</ParamField>

<ParamField body="exclude_out_of_stock" type="boolean" default="true">
  When enabled, out-of-stock products are excluded from search results by default. If you disable it, those products will keep appearing in searches.
</ParamField>

<ParamField body="language" type="string" default="es">
  Default store language. Affects localized messages returned by the API (for example, `friendly_message` in the search endpoints). Allowed values: `es`, `en`, `pt`.
</ParamField>

<ParamField body="default_order_by" type="string">
  Default ordering for the product list and search. Format: `field direction` (e.g., `price ASC`, `discount DESC`). Allowed fields: `price`, `discount`, `discount_value`, `created_at`, `name`, `score`, `category_order`. Directions: `ASC` or `DESC` (defaults to `DESC`). If not set, results are ordered by `score DESC`. Send `null` or an empty string to reset it.
</ParamField>

<ParamField body="use_v2_search" type="boolean">
  Enables the V2 search engine for the store.
</ParamField>

<ParamField body="search_synonyms" type="object">
  Synonym dictionary for search. Each key is a term and its value is a list of synonyms (each max. 100 characters). Example: `{ "phone": ["mobile", "smartphone"] }`. Send `null` to remove it.
</ParamField>

<ParamField body="search_stop_words" type="string[]">
  List of words the search ignores (stop words). Each max. 100 characters. Send `null` to remove it.
</ParamField>

<ParamField body="search_brands" type="string[]">
  List of brands recognized by the search. Each max. 100 characters. Send `null` to remove it.
</ParamField>

<ParamField body="show_initial_categories" type="boolean">
  Controls whether the store shows an initial set of categories (for example, when opening search without a term).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://gateway.jelou.ai/ecommerce/v1/apps/{app_id}/settings" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "currency": "COP",
      "tax_value": 0.19,
      "enable_per_product_tax": true,
      "exclude_out_of_stock": true,
      "language": "en"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "currency": "COP",
    "tax_value": 0.19,
    "exclude_out_of_stock": true,
    "enable_per_product_tax": true,
    "language": "en",
    "default_order_by": "price ASC",
    "use_v2_search": true,
    "search_synonyms": { "phone": ["mobile", "smartphone"] },
    "search_stop_words": ["the", "a", "of"],
    "search_brands": ["Nike", "Adidas"],
    "show_initial_categories": true
  }
  ```
</ResponseExample>

## Currency

The default currency for every store is `USD`. If you haven't configured a currency, prices will be displayed in US dollars.

### Common currencies

| Code  | Currency       |
| ----- | -------------- |
| `USD` | US Dollar      |
| `EUR` | Euro           |
| `COP` | Colombian Peso |
| `MXN` | Mexican Peso   |
| `PEN` | Peruvian Sol   |
| `CLP` | Chilean Peso   |
| `BRL` | Brazilian Real |
| `ARS` | Argentine Peso |

## Tax

Prices stored in Jelou Shop **include tax**. The configured rate is used to **extract** tax from the gross price:

```
net_price = price / (1 + tax_value)
tax       = price - net_price
```

**Example:** A product priced at `$11.50` with rate `0.15` (15%):

* Net price: `$11.50 / 1.15 = $10.00`
* Tax: `$11.50 - $10.00 = $1.50`

### Default rates by currency

If you don't configure `tax_value`, a default value is assigned based on the store's currency:

| Currency | Default rate |
| -------- | ------------ |
| `COP`    | 19% (`0.19`) |
| `PEN`    | 18% (`0.18`) |
| `MXN`    | 16% (`0.16`) |
| Others   | 15% (`0.15`) |

## Per-product tax

When `enable_per_product_tax` is active, you can assign an individual tax rate to each product using the `tax` field in the [products endpoint](/guides/integraciones/e-commerce/api-productos/upsert).

* If the product has `tax > 0`, that rate is used.
* If the product has `tax = 0` or it has not been configured, the store's `tax_value` is used as a fallback.
* For tax-exempt products, use `has_tax: false`.

The cart response will include a tax breakdown (`tax_breakdown`) grouped by rate when this option is active.

## Product availability

`exclude_out_of_stock` controls whether out-of-stock products appear in your store's search results:

* `true` (default): out-of-stock products are hidden from search endpoints.
* `false`: out-of-stock products keep appearing. Useful when you want shoppers to see the entire catalog even if there is no inventory available.

This setting only affects the default behavior of search endpoints. Products with `stock_type = "unlimited"` are always considered available.

## Language

`language` sets the store's default language and is used to localize API responses.

| Value | Language          |
| ----- | ----------------- |
| `es`  | Spanish (default) |
| `en`  | English           |
| `pt`  | Portuguese        |

It currently affects fields such as `friendly_message` returned by the search endpoints (`multi_search`, `v2_search`). The submitted value is normalized to lowercase.

<Note>
  Replace `{app_id}` with your store ID and `YOUR_API_KEY` with your [API key](/en/guides/configuracion/claves-api).
</Note>