### Request Single Recommendation

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

This example shows how to request a single set of product recommendations for a front page using a pre-configured recommendation key. The `context` can be empty if no specific context is needed.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k67361182d053e038d07a4efe",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode", "price", "imgUrl"],
        "deviceType": "DESKTOP",
        "context": {}
      }
    ]
  }'
```

--------------------------------

### Search Products, Categories, and Brands

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Execute a broad search across multiple content types. This example uses a wildcard query to retrieve all available products, categories, and brands.

```bash
curl -X POST "https://core.helloretail.com/serve/search/" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "*", \
    "key": "fd33f6d4-ca71-4fbf-b096-451e4872594f", \
    "trackingUserId": "67321f3a7f80eb30448b1279", \
    "format": "json", \
    "deviceType": "DESKTOP", \
    "products": { \
      "returnFilters": false, \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "categories": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "brands": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    } \
  }'
```

--------------------------------

### Get Recommendations with Brand Filters

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Use this to retrieve recommendations filtered by specific brands. Ensure the 'brand' field is included in the request context and filters.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{ \
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe", \
    "trackingUserId": "67321f3a7f80eb30448b1279", \
    "requests": [ \
      { \
        "trackingKey": "custom-1", \
        "fields": ["title", "originalUrl", "trackingCode", "brand"], \
        "hideAdditionalVariants": true, \
        "count": 8, \
        "deviceType": "DESKTOP", \
        "context": { \
          "brand": ["Nike", "Adidas"] \
        }, \
        "sources": [ \
          { \
            "type": "TOP", \
            "limit": 4, \
            "filters": { \
              "brand": {"$in": "$brand"} \
            } \
          }, \
          { \
            "type": "MOST_VIEWED", \
            "limit": 3, \
            "filters": { \
              "brand": {"$in": "$brand"} \
            } \
          } \
        ] \
      } \
    ] \
  }'
```

--------------------------------

### Search with Brand Filter

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Filter search results to include only products from a specific brand. This example limits results to 'Nike'.

```bash
curl -X POST "https://core.helloretail.com/serve/search/" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "*", \
    "key": "fd33f6d4-ca71-4fbf-b096-451e4872594f", \
    "trackingUserId": "67321f3a7f80eb30448b1279", \
    "format": "json", \
    "deviceType": "DESKTOP", \
    "products": { \
      "returnFilters": false, \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"], \
      "filters": ["brand:Nike"] \
    } \
  }'
```

--------------------------------

### Request Product Listing Page with $and Filter on Extra Data

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

This example demonstrates filtering products using multiple conditions on `extraDataList` with the `$and` operator. It's useful for complex filtering scenarios.

```bash
curl -X POST "https://core.helloretail.com/serve/pages/{pageId}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/category/winter-sports",
    "format": "json",
    "firstLoad": false,
    "trackingUserId": "",
    "deviceType": "DESKTOP",
    "params": {
      "filters": {
        "$and": [
          {"extraDataList.tags": "Accessory"},
          {"extraDataList.tags": "Sport"},
          {"extraDataList.tags": "Winter"}
        ]
      }
    },
    "products": {
      "start": 0,
      "count": 20,
      "fields": ["title", "originalUrl", "extraDataList.tags"],
      "filters": [],
      "sorting": []
    }
  }'
```

--------------------------------

### Fetch unmanaged product alternatives

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Requests multiple recommendation sets (alternatives and bought together) for a product page using URL context.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "trackingKey": "productpage-1",
        "fields": ["title", "originalUrl", "trackingCode"],
        "hideAdditionalVariants": true,
        "count": 8,
        "deviceType": "DESKTOP",
        "context": {
          "urls": ["https://www.example.com/products/snowboard"]
        },
        "sources": [
          {"type": "ALTERNATIVES", "limit": 4},
          {"type": "TOP"}
        ]
      },
      {
        "trackingKey": "productpage-2",
        "fields": ["title", "originalUrl", "trackingCode"],
        "hideAdditionalVariants": true,
        "count": 8,
        "deviceType": "DESKTOP",
        "context": {
          "urls": ["https://www.example.com/products/snowboard"]
        },
        "sources": [
          {"type": "BOUGHT_TOGETHER", "limit": 4},
          {"type": "TOP"}
        ]
      }
    ]
  }'
```

--------------------------------

### Fetch unmanaged recommendations with multiple sources

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Demonstrates the unmanaged API by defining multiple recommendation sources like TOP and MOST_BOUGHT.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "trackingKey": "frontpage-1",
        "fields": ["title", "originalUrl", "trackingCode", "price", "imgUrl"],
        "hideAdditionalVariants": true,
        "count": 8,
        "deviceType": "DESKTOP",
        "context": {},
        "sources": [
          {"type": "TOP", "limit": 4},
          {"type": "MOST_BOUGHT", "limit": 3},
          {"type": "TOP"}
        ]
      }
    ]
  }'
```

--------------------------------

### Create New Product

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Use the Product CRUD API to create a new product. This requires an API key for authentication and includes detailed product attributes.

```bash
curl -X POST "https://core.helloretail.com/api/websites/{websiteUuid}/products?apiKey={API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "https://www.example.com/products/new-sneakers/",
      "type": "products",
      "attributes": {
        "title": "New Running Sneakers",
        "productNumber": "SKU-123456",
        "variantProductNumbers": ["SKU-123456-S", "SKU-123456-M", "SKU-123456-L"],
        "imgUrl": "https://cdn.example.com/images/sneakers.jpg",
        "oldPrice": 149.99,
        "price": 119.99,
        "priceExVat": 95.99,
        "oldPriceExVat": 119.99,
        "currency": "USD",
        "brand": "Nike",
        "hierarchies": [
          ["Shoes", "Sneakers"],
          ["Men", "Sportswear"],
          ["Women", "Sportswear"]
        ],
        "description": "Lightweight running sneakers with advanced cushioning technology",
        "keywords": "running shoes sneakers sport athletic comfortable",
        "inStock": true,
        "url": "https://www.example.com/products/new-sneakers/",
        "ean": "5901234123457",
        "created": "2024-01-15 10:30:00",
        "extraData": {
          "color": "white",
          "material": "mesh"
        },
        "extraDataList": {
          "sizes": ["36", "37", "38", "39", "40", "41", "42"],
          "tags": ["running", "sport", "lightweight"]
        }
      }
    }
  }'
```

--------------------------------

### Fetch recommendations with URL context

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Uses a specific recommendation key and provides the current page URL in the context.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k67361182d053e038d07a4eec",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {
          "urls": ["https://www.example.com/products/snowboard"]
        }
      }
    ]
  }'
```

--------------------------------

### Track Conversion with Product Numbers

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Record a conversion event, specifying products by their product numbers. Include order details, total amount, and customer information.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/conversion" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "total": 2185.85,
    "orderNumber": "ORDER-12345",
    "email": "customer@example.com",
    "customerId": "CUST-789",
    "products": [
      {
        "productNumber": "14814386389327",
        "quantity": 1,
        "lineTotal": 785.95
      },
      {
        "productNumber": "14814386717007",
        "quantity": 2,
        "lineTotal": 699.95
      }
    ]
  }'
```

--------------------------------

### Fetch recommendations with product number context

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Provides a specific product number in the context to influence recommendation results.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k67361182d053e038d07a4eec",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {
          "productNumbers": ["14814386553167"]
        }
      }
    ]
  }'
```

--------------------------------

### Track Conversion with URLs

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Record a conversion event, specifying products by their URLs. This is an alternative to using product numbers for conversion tracking.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/conversion" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "total": 2185.85,
    "orderNumber": "ORDER-12346",
    "email": "customer@example.com",
    "customerId": "CUST-789",
    "products": [
      {
        "url": "https://www.example.com/products/snowboard",
        "quantity": 1,
        "lineTotal": 785.95
      },
      {
        "url": "https://www.example.com/products/bindings",
        "quantity": 2,
        "lineTotal": 699.95
      }
    ]
  }'
```

--------------------------------

### Retrieve Platform Plugin Information

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Fetch version and configuration details for Magento and WooCommerce plugins.

```bash
curl -X GET "https://www.your-store.com/rest/V1/awext/info" \
  -H "Authorization: Bearer tok_m2_{your_magento2_token}"
```

```bash
curl -X GET "https://www.your-store.com/awext/index/info" \
  -H "Authorization: Bearer tok_{your_magento1_token}"
```

```bash
curl -X GET "https://www.your-store.com/?feed=addwish_info" \
  -H "Authorization: Bearer tok_wc_{your_woocommerce_token}"
```

--------------------------------

### Manage Products via API

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Perform CRUD operations on products using the Products API. Requires a valid website UUID and API key.

```bash
curl -X GET "https://core.helloretail.com/api/websites/{websiteUuid}/products?id=https%3A%2F%2Fwww.example.com%2Fproducts%2Fnew-sneakers%2F&apiKey={API-KEY}"
```

```bash
curl -X PATCH "https://core.helloretail.com/api/websites/{websiteUuid}/products?id=https%3A%2F%2Fwww.example.com%2Fproducts%2Fnew-sneakers%2F&apiKey={API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "https://www.example.com/products/new-sneakers-updated/",
      "type": "products",
      "attributes": {
        "title": "New Running Sneakers - Updated Edition",
        "price": 99.99,
        "oldPrice": 149.99,
        "inStock": true,
        "url": "https://www.example.com/products/new-sneakers-updated/",
        "extraData": {
          "color": "black",
          "material": "mesh"
        }
      }
    }
  }'
```

```bash
curl -X DELETE "https://core.helloretail.com/api/websites/{websiteUuid}/products?id=https%3A%2F%2Fwww.example.com%2Fproducts%2Fnew-sneakers%2F&apiKey={API-KEY}"
```

--------------------------------

### Configure Page Settings

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Fetch or update page configurations, including personalized and product-specific boosts. Requires companyId, websiteUuid, and pageKey or versionId.

```bash
curl -X GET "https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/latest/{pageKey}?apiKey={apiKey}" \
  -H "Content-Type: application/json"
```

```bash
curl -X PATCH "https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}?apiKey={apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "page",
      "attributes": {
        "state": "DRAFT",
        "personalized_boosts": [
          {"field": "product.hierarchy", "boost": 2},
          {"field": "product.brand", "boost": 2},
          {"field": "product.pi.budgetZone", "boost": 3},
          {"field": "product.pi.productCluster", "boost": 4}
        ]
      }
    }
  }'
```

```bash
curl -X PATCH "https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}?apiKey={apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "page",
      "attributes": {
        "state": "DRAFT",
        "product_boosts": [
          {"field": "brand", "value": "Nike", "boost": 4},
          {"field": "extraDataList.tags", "value": "Sport", "boost": 4},
          {"field": "inStock", "value": "false", "boost": -1}
        ]
      }
    }
  }'
```

--------------------------------

### POST /api/websites/{websiteUuid}/products

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Creates a new product in the catalog.

```APIDOC
## POST /api/websites/{websiteUuid}/products

### Description
Creates a new product entry in the catalog. Requires an API key.

### Method
POST

### Endpoint
https://core.helloretail.com/api/websites/{websiteUuid}/products?apiKey={API-KEY}

### Parameters
#### Path Parameters
- **websiteUuid** (string) - Required - The website identifier

#### Query Parameters
- **apiKey** (string) - Required - Authentication key

### Request Body
- **data** (object) - Required - Product data object

### Request Example
{
  "data": {
    "id": "https://www.example.com/products/new-sneakers/",
    "type": "products",
    "attributes": {
      "title": "New Running Sneakers",
      "productNumber": "SKU-123456"
    }
  }
}
```

--------------------------------

### POST /serve/pages/{pageId}

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Serves dynamic product listing pages with support for filters, sorting, and pagination.

```APIDOC
## POST /serve/pages/{pageId}

### Description
Serves dynamic product listing pages with support for filters, sorting, and pagination. It enables building category pages, brand pages, or any filtered product view.

### Method
POST

### Endpoint
https://core.helloretail.com/serve/pages/{pageId}

### Parameters
#### Path Parameters
- **pageId** (string) - Required - The unique identifier for the page configuration.

#### Request Body
- **url** (string) - Required - The current page URL.
- **format** (string) - Required - The response format (e.g., "json").
- **firstLoad** (boolean) - Required - Indicates if this is the initial page load.
- **trackingUserId** (string) - Optional - The unique identifier for the user.
- **deviceType** (string) - Optional - The device type (e.g., "DESKTOP").
- **params** (object) - Optional - Filtering parameters including hierarchies or extraDataList tags.
- **products** (object) - Optional - Product configuration including start, count, fields, filters, and sorting.

### Request Example
{
  "url": "https://www.example.com/category/accessories",
  "format": "json",
  "firstLoad": true,
  "trackingUserId": "67321f3a7f80eb30448b1279",
  "deviceType": "DESKTOP",
  "params": {
    "filters": {
      "hierarchies": ["accessories"]
    }
  },
  "products": {
    "start": 0,
    "count": 20,
    "fields": ["productNumber", "title", "hierarchies", "brand", "trackingCode"],
    "filters": ["brand:Nike"],
    "sorting": ["price asc"]
  }
}
```

--------------------------------

### Request Multiple Recommendations in One Request

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

This snippet demonstrates how to fetch multiple sets of recommendations by including several request objects within a single API call. Each request can use a different recommendation key.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k67361182d053e038d07a4efe",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {}
      },
      {
        "key": "k67361182d053e038d07a4ef8",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {}
      }
    ]
  }'
```

--------------------------------

### Fetch recommendations with custom brand and extra data

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Includes custom brand information and extra data fields within the request context.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k673613c085074171ef9f9d9d",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {
          "brand": "Nike",
          "extraData": {
            "isAccessory": "true"
          },
          "extraDataList": {
            "tags": ["Sport"]
          }
        }
      }
    ]
  }'
```

--------------------------------

### Basic Product Search

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Perform a full-text search for products. Specify the fields you want to retrieve and the desired count.

```bash
curl -X POST "https://core.helloretail.com/serve/search/" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "snowboard", \
    "key": "fd33f6d4-ca71-4fbf-b096-451e4872594f", \
    "trackingUserId": "67321f3a7f80eb30448b1279", \
    "format": "json", \
    "deviceType": "DESKTOP", \
    "products": { \
      "returnFilters": false, \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode", "price", "imgUrl"] \
    } \
  }'
```

--------------------------------

### Full Search with All Content Types and Redirects

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Perform a comprehensive search including products, categories, brands, site pages, blog posts, and redirects. This is useful for broad content discovery.

```bash
curl -X POST "https://core.helloretail.com/serve/search/" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "winter gear", \
    "key": "40cce1a0-aab6-4855-a279-86a53a29c8b4", \
    "trackingUserId": "67321f3a7f80eb30448b1279", \
    "format": "json", \
    "deviceType": "DESKTOP", \
    "products": { \
      "returnFilters": false, \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "categories": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "brands": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "sitePages": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "blogPosts": { \
      "start": 0, \
      "count": 10, \
      "fields": ["title", "originalUrl", "trackingCode"] \
    }, \
    "redirects": { \
      "start": 0, \
      "count": 2 \
    } \
  }'
```

--------------------------------

### Fetch recommendations with hierarchy context

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Uses category hierarchies in the context to filter or influence the returned recommendations.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "key": "k67361182d053e038d07a4ede",
        "format": "json",
        "fields": ["title", "originalUrl", "trackingCode"],
        "deviceType": "DESKTOP",
        "context": {
          "hierarchies": [["accessories"]]
        }
      }
    ]
  }'
```

--------------------------------

### POST /serve/recoms

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Serves product recommendations using pre-configured recommendation keys defined in the Hello Retail dashboard.

```APIDOC
## POST /serve/recoms

### Description
Serves product recommendations using pre-configured recommendation keys. Each key defines the algorithm and business rules for the recommendation.

### Method
POST

### Endpoint
https://core.helloretail.com/serve/recoms

### Parameters
#### Request Body
- **trackingUserId** (string) - Optional - The unique identifier for the user.
- **requests** (array) - Required - A list of recommendation request objects.

### Request Example
{
  "trackingUserId": "67321f3a7f80eb30448b1279",
  "requests": [
    {
      "key": "k67361182d053e038d07a4efe",
      "format": "json",
      "fields": ["title", "originalUrl", "trackingCode", "price", "imgUrl"],
      "deviceType": "DESKTOP",
      "context": {}
    }
  ]
}
```

--------------------------------

### Trigger Product Feed Imports

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Queue or force product feed runs to synchronize catalog data. Use the full parameter to ignore delta feed settings.

```bash
curl -X POST "https://core.helloretail.com/api/websites/{websiteUuid}/productfeedruns/{feedId}?apiKey={API-KEY}" \
  -H "Content-Type: application/json"
```

```bash
curl -X POST "https://core.helloretail.com/api/websites/{websiteUuid}/productfeedruns/{feedId}?apiKey={API-KEY}&full=true" \
  -H "Content-Type: application/json"
```

--------------------------------

### Fetch unmanaged category recommendations with hierarchy filter

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Applies a hierarchy filter directly within the recommendation source configuration.

```bash
curl -X POST "https://core.helloretail.com/serve/recoms" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "requests": [
      {
        "trackingKey": "categorypage-1",
        "fields": ["title", "originalUrl", "trackingCode"],
        "hideAdditionalVariants": true,
        "count": 8,
        "deviceType": "DESKTOP",
        "context": {
          "hierarchies": [["Snowboard"]]
        },
        "sources": [
          {
            "type": "TOP",
            "filters": {
              "hierarchies": {"$in": "$hierarchies"}
            }
          }
        ]
      }
    ]
  }'
```

--------------------------------

### Query Product Intelligence Metrics

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Access advanced product analytics via GraphQL. Requires a valid API key.

```bash
curl -X POST "https://core.helloretail.com/pi/graphql?apiKey={API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { productInsight(url: \"https://www.example.com/products/snowboard\", website: \"d364dcdc-e618-45bd-b395-8653579884fe\") { productLifetimeValue retentionRate isRecurrent overallRecurrence recurringPeriodWeekly { start end } returnsPeriodWeekly { start end } recurrenceDataWeekly { week probability } discountData { percentageRangeFrom percentageRangeTo probability } } }"
  }'
```

--------------------------------

### Track Click from Recommendation

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Record a click event originating from a recommendation. The 'source' field should contain details about the recommendation context.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/click" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "source": "ps-74b19399-447e-4ea7-8550-3fcdba1fb4bd|63483b0be52a6801e489b0b4|*|pos:0|per:true|"
  }'
```

--------------------------------

### POST /serve/collect/click

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Tracks a click event from a recommendation source.

```APIDOC
## POST /serve/collect/click

### Description
Tracks a user click event originating from a recommendation.

### Method
POST

### Endpoint
https://core.helloretail.com/serve/collect/click

### Request Body
- **trackingUserId** (string) - Required - Unique identifier for the user
- **websiteUuid** (string) - Required - Unique identifier for the website
- **source** (string) - Required - The recommendation source string

### Request Example
{
  "trackingUserId": "67321f3a7f80eb30448b1279",
  "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
  "source": "ps-74b19399-447e-4ea7-8550-3fcdba1fb4bd|63483b0be52a6801e489b0b4|*|pos:0|per:true|"
}
```

--------------------------------

### Track Page View by Product Number

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Track a page view by specifying the product number. This is useful when the product can be identified directly without needing its URL.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/pageview" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "https://www.example.com/products/ski-wax",
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "referrer": "https://www.example.com/",
    "productNumber": "14814386553167"
  }'
```

--------------------------------

### Request Product Listing Page with Hierarchy Filter

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Use this snippet to fetch a product listing page filtered by a specific hierarchy. Ensure the `pageId` is correctly set in the URL.

```bash
curl -X POST "https://core.helloretail.com/serve/pages/{pageId}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/category/accessories",
    "format": "json",
    "firstLoad": true,
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "deviceType": "DESKTOP",
    "params": {
      "filters": {
        "hierarchies": ["accessories"]
      }
    },
    "products": {
      "start": 0,
      "count": 20,
      "fields": ["productNumber", "title", "hierarchies", "brand", "trackingCode"],
      "filters": ["brand:Nike"],
      "sorting": ["price asc"]
    }
  }'
```

--------------------------------

### Configure Search Personalization via GraphQL

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Update or clear search algorithm personalization fields using GraphQL mutations.

```bash
curl -X POST "https://core.helloretail.com/graphql?apiKey={apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateSearchPersonalization { updateSearchAlgorithmPersonalization(personalization: { algorithmId: \"8013\" personalizedFields: [ { field: \"product.pi.budgetZone\" boostValue: 5 } { field: \"product.pi.productCluster\" boostValue: 3 } { field: \"product.hierarchy\" boostValue: 3 } ] }) { allowedFields availableFields personalizedFields { field boostValue } } }",
    "operationName": "UpdateSearchPersonalization"
  }'
```

```bash
curl -X POST "https://core.helloretail.com/graphql?apiKey={apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateSearchPersonalization { updateSearchAlgorithmPersonalization(personalization: { algorithmId: \"8013\" personalizedFields: [] }) { allowedFields availableFields personalizedFields { field boostValue } } }",
    "operationName": "UpdateSearchPersonalization"
  }'
```

--------------------------------

### Track Page View by URL

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Use this endpoint to track a page view by providing the URL of the viewed page. Ensure all required fields like trackingUserId, websiteUuid, and location are included.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/pageview" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "https://www.example.com/products/snowboard",
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "referrer": "https://www.example.com",
    "url": "https://www.example.com/products/snowboard"
  }'
```

--------------------------------

### Page Configuration API

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

APIs for configuring page solutions including boosts, overrides, and stock settings.

```APIDOC
## GET /api/companies/{companyId}/websites/{websiteUuid}/pages/latest/{pageKey}

### Description
Fetches the latest page configuration.

### Method
GET

### Endpoint
https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/latest/{pageKey}

### Query Parameters
- **apiKey** (string) - Required - Your API key.

### Response
#### Success Response (200)
- **[Page Configuration Object]** (object) - The latest configuration for the specified page.

### Response Example
```json
{
  "data": {
    "type": "page",
    "id": "some-version-id",
    "attributes": {
      "state": "PUBLISHED",
      "personalized_boosts": [],
      "product_boosts": []
    }
  }
}
```
```

```APIDOC
## PATCH /api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}

### Description
Updates a page configuration, for example, to add personalized boosts.

### Method
PATCH

### Endpoint
https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}

### Query Parameters
- **apiKey** (string) - Required - Your API key.

### Request Body
- **data** (object) - Required - The page data to update.
  - **type** (string) - Required - The resource type, should be "page".
  - **attributes** (object) - Required - The attributes to update.
    - **state** (string) - Optional - The state of the page (e.g., "DRAFT", "PUBLISHED").
    - **personalized_boosts** (array of objects) - Optional - A list of personalized boosts to apply.
      - **field** (string) - Required - The field to boost.
      - **boost** (number) - Required - The boost value.

### Request Example
```json
{
  "data": {
    "type": "page",
    "attributes": {
      "state": "DRAFT",
      "personalized_boosts": [
        {"field": "product.hierarchy", "boost": 2},
        {"field": "product.brand", "boost": 2},
        {"field": "product.pi.budgetZone", "boost": 3},
        {"field": "product.pi.productCluster", "boost": 4}
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **[Updated Page Configuration Object]** (object) - Details of the updated page configuration.

### Response Example
```json
{
  "data": {
    "type": "page",
    "id": "{versionId}",
    "attributes": {
      "state": "DRAFT",
      "personalized_boosts": [
        {"field": "product.hierarchy", "boost": 2},
        {"field": "product.brand", "boost": 2},
        {"field": "product.pi.budgetZone", "boost": 3},
        {"field": "product.pi.productCluster", "boost": 4}
      ]
    }
  }
}
```
```

```APIDOC
## PATCH /api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}

### Description
Updates a page configuration, for example, to add product boosts.

### Method
PATCH

### Endpoint
https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}

### Query Parameters
- **apiKey** (string) - Required - Your API key.

### Request Body
- **data** (object) - Required - The page data to update.
  - **type** (string) - Required - The resource type, should be "page".
  - **attributes** (object) - Required - The attributes to update.
    - **state** (string) - Optional - The state of the page (e.g., "DRAFT", "PUBLISHED").
    - **product_boosts** (array of objects) - Optional - A list of product boosts to apply.
      - **field** (string) - Required - The field to boost.
      - **value** (string) - Required - The value of the field to match.
      - **boost** (number) - Required - The boost value.

### Request Example
```json
{
  "data": {
    "type": "page",
    "attributes": {
      "state": "DRAFT",
      "product_boosts": [
        {"field": "brand", "value": "Nike", "boost": 4},
        {"field": "extraDataList.tags", "value": "Sport", "boost": 4},
        {"field": "inStock", "value": "false", "boost": -1}
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **[Updated Page Configuration Object]** (object) - Details of the updated page configuration.

### Response Example
```json
{
  "data": {
    "type": "page",
    "id": "{versionId}",
    "attributes": {
      "state": "DRAFT",
      "product_boosts": [
        {"field": "brand", "value": "Nike", "boost": 4},
        {"field": "extraDataList.tags", "value": "Sport", "boost": 4},
        {"field": "inStock", "value": "false", "boost": -1}
      ]
    }
  }
}
```
```

--------------------------------

### Track Cart Update with URLs

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Update the user's cart by providing a list of product URLs. This method is an alternative to using product numbers.

```bash
curl -X POST "https://core.helloretail.com/serve/collect/cart" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUserId": "67321f3a7f80eb30448b1279",
    "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
    "total": 199.95,
    "url": "https://www.example.com/cart",
    "urls": ["https://www.example.com/products/ski-wax"],
    "email": "customer@example.com"
  }'
```

--------------------------------

### POST /serve/collect/conversion

Source: https://context7.com/helloretail/api-usage-examples/llms.txt

Tracks a completed order or conversion event.

```APIDOC
## POST /serve/collect/conversion

### Description
Records a conversion event with order details.

### Method
POST

### Endpoint
https://core.helloretail.com/serve/collect/conversion

### Request Body
- **trackingUserId** (string) - Required - Unique identifier for the user
- **websiteUuid** (string) - Required - Unique identifier for the website
- **total** (number) - Required - Order total
- **orderNumber** (string) - Required - Unique order identifier
- **email** (string) - Optional - Customer email
- **customerId** (string) - Optional - Customer identifier
- **products** (array) - Required - List of products in the order

### Request Example
{
  "trackingUserId": "67321f3a7f80eb30448b1279",
  "websiteUuid": "d364dcdc-e618-45bd-b395-8653579884fe",
  "total": 2185.85,
  "orderNumber": "ORDER-12345",
  "email": "customer@example.com",
  "customerId": "CUST-789",
  "products": [
    { "productNumber": "14814386389327", "quantity": 1, "lineTotal": 785.95 }
  ]
}
```