### Full Context Example

Source: https://docs.athoscommerce.com/reference/context-object-guide

Example of a comprehensive context object, recommended for server-side integrations.

```APIDOC
## Full Context Example

### Description
This example includes all recommended fields for the `context` object, particularly useful for server-side integrations. Ensure you provide the shopper's `IP` and `userAgent`, not the server's.

### Request Example
```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...".",
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/products/blue-shirt",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user@example.com",
    "initiator": "athos/custom/1.0",
    "currency": { "code": "USD" }
  }
}
```
```

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

### Banner Clickthrough Event Example

Source: https://docs.athoscommerce.com/reference/autocomplete-clickthrough

This example shows the structure for a clickthrough event when a banner is clicked. It includes the same context as the product example but specifies banner UIDs in the data.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "banners": [
      {
        "uid": "8128168755498"
      }
    ]
  }
}
```

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

### Example Render Context

Source: https://docs.athoscommerce.com/reference/recommendations-render

Example JSON object representing the context for a recommendation render event.

```json
"context": {
            "IP": "7309:1fdb:e0d5:7632:7f2a:c269:7519:991b",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
            "timestamp": "2024-06-11T17:47:04.075876Z",
            "pageUrl": "https://imaginary.storefront.com/collections/mens/products/adventure-shorts-pitch-black",
            "userId": "41f87850-65f5-4546-851c-f166109e57b9",
            "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
            "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
            "shopperId": "user123456",
            "initiator": "athos/custom/1.0",
            "attribution": [
              {
                "type": "email",
                "id": "1234567890"
              }
            ],
            "currency": {
```

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

### Product Clickthrough Event Example

Source: https://docs.athoscommerce.com/reference/autocomplete-clickthrough

This example demonstrates the structure for a clickthrough event when a product is clicked. It includes detailed context and the product's response data.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331900000",
        "uid": "8128331907370"
      }
    ]
  }
}
```

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

### Index Status Response Example

Source: https://docs.athoscommerce.com/reference/bulk_indexing_api

This is an example of a successful response from the Status Endpoint, indicating the index is done.

```json
{
  "status": "success",
  "feeds": [{
      "id": 1143,
      "lastIndexed": "2017-05-30T13:50:25+0000",
      "nextIndexTime": "2017-05-30T16:03:42+0000",
      "indexStatus": "done"
  }]
}
```

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

### Impression Example

Source: https://docs.athoscommerce.com/reference/category-impression

An example of an impression event payload.

```APIDOC
## Impression Example

### Request Example
```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      },
      {
        "type": "product",
        "parentId": "8128331933333",
        "uid": "8127879741738"
      },
      {
        "type": "product",
        "parentId": "8128331944444",
        "uid": "8128173736234"
      }
    ],
    "banners": [
      {
        "uid": "8128168755498"
      }
    ]
  }
}
```
```

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

### Example Clickthrough Request for Product Results

Source: https://docs.athoscommerce.com/reference/search-clickthrough

This example shows the structure for a clickthrough event when tracking product results. It includes context and specifies the product's parent ID and UID.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}
```

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

### Product Result Banner Schema Example

Source: https://docs.athoscommerce.com/reference/category-impression

This example demonstrates the structure of an impression event, including context and data related to product results and banners.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      },
      {
        "type": "product",
        "parentId": "8128331933333",
        "uid": "8127879741738"
      },
      {
        "type": "product",
        "parentId": "8128331944444",
        "uid": "8128173736234"
      }
    ],
    "banners": [
      {
        "uid": "8128168755498"
      }
    ]
  }
}
```

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

### Full Context Object Example

Source: https://docs.athoscommerce.com/reference/context-object-guide

This example shows a comprehensive context object, recommended for server-side integrations. It includes shopper IP and user agent, which should be from the shopper's environment, not the server's.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/products/blue-shirt",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user@example.com",
    "initiator": "athos/custom/1.0",
    "currency": { "code": "USD" }
  }
}
```

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

### Example Recommendation Impression Event

Source: https://docs.athoscommerce.com/reference/recommendations-impression

An example of a recommendation impression event, including detailed context and a list of product results and banners.

```json
{
  "context": {
    "IP": "7309:1fdb:e0d5:7632:7f2a:c269:7519:991b",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://imaginary.storefront.com/collections/mens/products/adventure-shorts-pitch-black",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "attribution": [
      {
        "type": "email",
        "id": "1234567890"
      }
    ],
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "tag": "similar",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      },
      {
        "type": "product",
        "parentId": "8128331933333",
        "uid": "8127879741738"
      },
      {
        "type": "product",
        "parentId": "8128331944444",
        "uid": "8128173736234"
      },
      {
        "type": "product",
        "parentId": "8128331955555",
        "uid": "8128273711402"
      },
      {
        "type": "product",
        "parentId": "8128331966666",
        "uid": "8128028737834"
      }
    ],
    "banners": [
      {
        "uid": "8128168755498"
      }
    ]
  }
}
```

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

### Example: Product Pageview Event Payload

Source: https://docs.athoscommerce.com/reference/shopping-platform-tracking-guide

Example JSON payload for tracking when a shopper views a product detail page. Requires context and a data object with the product's result information.

```json
{
  "context": { /* see context guide */ },
  "data": {
    "result": {
      "parentId": "1234511111",
      "uid": "1234567890"
    }
  }
}
```

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

### Enable Beacon Tracking (GET)

Source: https://docs.athoscommerce.com/reference/personalized-recommendations

Include `beacon=true` as a query parameter in GET requests to enable the Beacon 2.0 tracking system, which automatically generates tracking events.

```http
https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?tags=similar&products=123-ABC&beacon=true&...
```

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

### Impression Example

Source: https://docs.athoscommerce.com/reference/autocomplete-impression

An example of an impression event payload, including context and data for tracking product results and banners.

```APIDOC
## Impression Example

### Request Body Example
```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      },
      {
        "type": "product",
        "parentId": "8128331933333",
        "uid": "8127879741738"
      },
      {
        "type": "product",
        "parentId": "8128331944444",
        "uid": "8128173736234"
      }
    ],
    "banners": [
      {
        "uid": "8128168755498"
      }
    ]
  }
}
```
```

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

### Minimum Required Context Fields

Source: https://docs.athoscommerce.com/reference/context-object-guide

Example demonstrating the minimum required fields for the context object.

```APIDOC
## Minimum Required Context Fields

### Description
This example shows the essential fields needed for the `context` object in a beacon event payload.

### Request Example
```json
{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/search?q=shirts",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "initiator": "athos/custom/1.0"
  }
}
```
```

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

### Example: Shopper Login Event Payload

Source: https://docs.athoscommerce.com/reference/shopping-platform-tracking-guide

Example JSON payload for tracking a shopper login event. This event only requires a context object, with 'shopperId' being a mandatory field within the context.

```json
{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/login",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": { "code": "USD" }
  }
}
```

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

### PUT Request Example for Feed Submission

Source: https://docs.athoscommerce.com/reference/bulk_indexing_api

Use this example for updating an existing feed. Request parameters must be included in the query string for PUT requests. The feed file is not sent directly with this method.

```curl
curl -v -XPUT -u foobar:abc123def456ghi789 https://index-api.athoscommerce.net/api/index/feed?feedId=42
```

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

### GET /meta

Source: https://docs.athoscommerce.com/reference/get-meta-category

Retrieves static search configuration data, including badge configurations.

```APIDOC
## GET /meta

### Description
Returns static search configuration data, most notably, badge configurations.

### Method
GET

### Endpoint
/meta

### Parameters
#### Query Parameters
- **siteId** (string) - Required - Unique identifier to associate the Athos account making the request to the database. This can be found on the [My Account](https://console.athoscommerce.net/my-account) page in the Athos Management Console under the **Account details** section.

### Response
#### Success Response (200)
- **sortOptions** (array) - An array of available sorting options.
- **facets** (object) - An object containing facet configurations for search filtering.

#### Response Example
```json
{
  "sortOptions": [
    {
      "type": "field",
      "field": "price",
      "direction": "asc",
      "label": "Price Low to High"
    }
  ],
  "facets": {
    "color": {
      "display": "palette",
      "label": "Color",
      "collapsed": false,
      "multiple": "or"
    }
  }
}
```
```

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

### POST Request Example for Feed Submission

Source: https://docs.athoscommerce.com/reference/bulk_indexing_api

Use this example when uploading a new feed file. The feed file is sent as form data. Ensure the feedId and requestedBy parameters are correctly formatted in the query string.

```curl
curl -v -XPOST -u foobar:abc123def456ghi789 -F feedFile=@/path/to/feed_file.zip "https://index-api.athoscommerce.net/api/index/feed?feedId=42&requestedBy=myemail%40searchspring.com"
```

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

### Example: Cart Add Event Payload

Source: https://docs.athoscommerce.com/reference/shopping-platform-tracking-guide

Example JSON payload for tracking when a shopper adds an item to their cart. Includes context and data with results and the updated cart state.

```json
{
  "context": { /* see context guide */ },
  "data": {
    "results": [
      {
        "parentId": "0987611111",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ],
    "cart": [
      {
        "parentId": "0987622222",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      },
      {
        "parentId": "0987633333",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ]
  }
}
```

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

### Results Impression Example

Source: https://docs.athoscommerce.com/reference/category-impression

An example of an impression event payload focusing on results.

```APIDOC
## Results Impression Example

### Request Example
```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ]
  }
}
```
```

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

### Example Remove from Cart Request

Source: https://docs.athoscommerce.com/reference/cart-remove

An example request body for removing an item from the cart.

```APIDOC
## POST /cart/remove

### Description
Removes a specified product from the shopping cart.

### Method
POST

### Endpoint
/cart/remove

### Request Body
- **context** (object) - Required - Contextual data about the event.
- **data** (object) - Required - Event details.
  - **results** (array) - Required - Product(s) to be removed from the cart.
    - **items** (object) - Reference to the Product Schema.

### Request Example
```json
{
  "context": {
    "IP": "7309:1fdb:e0d5:7632:7f2a:c269:7519:991b",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "timestamp": "2023-10-27T10:00:00Z",
    "pageUrl": "https://example.com/cart",
    "userId": "user123",
    "sessionId": "session456",
    "pageLoadId": "pageload789",
    "initiator": "remove_button"
  },
  "data": {
    "results": [
      {
        "parentId": "parent001",
        "uid": "product001",
        "sku": "SKU001",
        "qty": 1,
        "price": 19.99
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **context** (object) - Contextual data about the event.
- **data** (object) - Event details.
  - **results** (array) - Product(s) that were removed from the cart.
    - **items** (object) - Reference to the Product Schema.
  - **cart** (array) - Updated current cart products.
    - **items** (object) - Reference to the Product Schema.

#### Response Example
```json
{
  "context": {
    "IP": "7309:1fdb:e0d5:7632:7f2a:c269:7519:991b",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "timestamp": "2023-10-27T10:00:05Z",
    "pageUrl": "https://example.com/cart",
    "userId": "user123",
    "sessionId": "session456",
    "pageLoadId": "pageload789",
    "initiator": "remove_button"
  },
  "data": {
    "results": [
      {
        "parentId": "parent001",
        "uid": "product001",
        "sku": "SKU001",
        "qty": 1,
        "price": 19.99
      }
    ],
    "cart": [
      {
        "parentId": "parent002",
        "uid": "product002",
        "sku": "SKU002",
        "qty": 2,
        "price": 29.99
      }
    ]
  }
}
```
```

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

### Install and Initialize Beacon.js via NPM

Source: https://docs.athoscommerce.com/reference/Beacon-js

Use the NPM package for full lifecycle control in single-page applications. Initialize with a siteId and track events like autocomplete renders or product page views.

```bash
npm install --save @athoscommerce/beacon
```

```typescript
import { Beacon } from '@athoscommerce/beacon';

// Initialize Beacon with required siteId
const beacon = new Beacon({ 
  siteId: 'abc123',
  currency: { code: 'USD' }
});

// Track an autocomplete render event
beacon.events.autocomplete.render({
  data: {
    // ... render data
  }
});

// Track a product page view
beacon.events.product.pageView({
  data: {
    result: {
      uid: 'product-123',
      sku: 'SKU-123',
      parentId: 'parent-123'
    }
  }
});
```

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

### Validation Error Examples

Source: https://docs.athoscommerce.com/reference/search-redirect

Examples of validation errors that occur when request data does not meet the expected format or constraints.

```APIDOC
## Validation Error Examples

### Description
These examples illustrate common validation errors returned by the API when the request payload does not conform to the expected schema or business rules.

### Examples

#### If array is defined must not be empty
```json
{
  "success": false,
  "error": "ValidationError",
  "messages": [
    "if `data.merchandising.triggeredCampaigns[0].variationId` key-value is defined, `data.merchandising.triggeredCampaigns[0].experimentId` key-value is required"
  ],
  "data": "{\n    \"context\": { /* varies by endpoint */},\n    \"data\": { */varies by endoint */ }"
}
```

#### Unknown field
```json
{
  "success": false,
  "error": "ValidationError",
  "messages": [
    "request body contains unknown field: \"seed\""
  ],
  "data": "{\n    \"context\": { /* varies by endpoint */},\n    \"data\": { */varies by endoint */ }"
}
```
```

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

### Perform Basic Beacon Initialization

Source: https://docs.athoscommerce.com/reference/Beacon-js

Initialize the Beacon instance by providing the required siteId in the Globals object.

```javascript
import { Beacon } from '@athoscommerce/beacon';

const beacon = new Beacon({ 
  siteId: 'abc123' // Your Athos Site ID
});
```

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

### Results Impression Schema Example

Source: https://docs.athoscommerce.com/reference/category-impression

This example shows the structure for an impression event focused on results, including context and specific result details.

```json
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": {
      "code": "USD"
    }
  },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ]
  }
}
```

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

### Context Object Best Practices

Source: https://docs.athoscommerce.com/reference/context-object-guide

Guidelines for effectively using the context object, including identifier management, timestamps, authentication, and testing.

```APIDOC
## Best Practices for Context Object

### Identifier Management
- Use UUIDs (v4) for all identifier generation.

### Timestamps
- Use RFC3339 format with UTC timezone: `YYYY-MM-DDTHH:mm:ss.sssZ`.
- Capture the event's occurrence time, not when it is sent.

### Authentication
- Include `shopperId` when the user is logged in.
- `shopperId` is required for the `/shopper/login` endpoint and for personalization.

### Testing
- Set `dev: true` during testing to prevent affecting production reports.
```

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

### Specify Brands for Brand Trending (GET)

Source: https://docs.athoscommerce.com/reference/personalized-recommendations

For GET requests using Brand Trending, provide a comma-separated list of brand names in the 'brands' parameter.

```http
https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?brands=brandA,brandB,brandC&...
```

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

### Specify Categories for Category Trending (GET)

Source: https://docs.athoscommerce.com/reference/personalized-recommendations

For GET requests using Category Trending, provide a comma-separated list of category IDs in the 'categories' parameter.

```http
https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?categories=cat1,cat2,cat3&...
```

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

### Integrate Beacon.js via CDN

Source: https://docs.athoscommerce.com/reference/Beacon-js

Add this script tag before the closing </head> tag to make the tracker globally available via window.athos.tracker.

```html
<script siteId="YOUR_SITE_ID" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>
```

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

### Enable Test Mode for Tracking (GET)

Source: https://docs.athoscommerce.com/reference/personalized-recommendations

Append `test=true` to GET requests along with `beacon=true` to mark tracking events as test events, preventing them from affecting analytics.

```http
https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?tags=similar&products=123-ABC&beacon=true&test=true&...
```

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

### Example: Cart Remove Event Payload

Source: https://docs.athoscommerce.com/reference/shopping-platform-tracking-guide

Example JSON payload for tracking when a shopper removes an item from their cart. Includes context and data with results and the updated cart state.

```json
{
  "context": { /* see context guide */ },
  "data": {
    "results": [
      {
        "parentId": "0987633333",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ],
    "cart": [
      {
        "parentId": "0987622222",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ]
  }
}
```

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

### Minimum Required Context Fields

Source: https://docs.athoscommerce.com/reference/context-object-guide

This example demonstrates the minimum set of fields required for the context object in a beacon event payload. Ensure all these fields are populated for accurate reporting.

```json
{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/search?q=shirts",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "initiator": "athos/custom/1.0"
  }
}
```

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

### Filter Recommendations by Field (GET)

Source: https://docs.athoscommerce.com/reference/personalized-recommendations

Use the 'filter.[field]=[value]' format for GET requests to filter recommendations. Ensure the field is enabled for filtering in the Athos Management Console.

```http
https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?filter.color=blue&...
```

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

### GET /recommend

Source: https://docs.athoscommerce.com/reference/bundle-recommendations

Retrieves bundle recommendations based on the specified profile. The base URL is https://{siteId}.a.p13n.athoscommerce.net/v1/recommend. Remember to replace {siteId} with your actual site ID.

```APIDOC
## GET /recommend

### Description
Retrieves bundle recommendations. The logic applied depends on the `profile` parameter. A 'seed' item may be prepended to the response for specific profiles.

### Method
GET

### Endpoint
`https://{siteId}.a.p13n.athoscommerce.net/v1/recommend`

### Parameters
#### Query Parameters
- **profile** (string) - Required - The type of bundle profile to use (e.g., `cross-sell`, `cart-cross-sell`, `trending`, `category-brand`, `custom`).
- **products** (string) - Optional - Used for seeded bundles to pass the ID of the product used to generate the bundle. Required for `cross-sell` and `category-brand` profiles when a seed is needed.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
An array of product bundles. For seeded bundles, the first item in the `results` array will have the `bundleSeed: true` flag.

- **responseId** (string) - Unique identifier for the recommendation response.
- **profile** (object) - Information about the profile used.
  - **tag** (string) - The tag of the profile.
- **results** (array) - An array of recommended products.
  - **id** (string) - The product ID.
  - **mappings** (object) - Product mapping details.
    - **core** (object) - Core product information.
      - **name** (string) - Product name.
      - **price** (number) - Product price.
      - **sku** (string) - Product SKU.
      - **imageUrl** (string) - URL of the product image.
      - **available** (boolean) - Availability status.
  - **variants** (object) - Product variants.
    - **data** (array) - Array of variant data.
      - **mappings** (object) - Variant mapping details.
        - **core** (object) - Core variant information.
          - **uid** (string) - Variant UID.
          - **price** (number) - Variant price.
      - **options** (object) - Variant options (e.g., color, size).
        - **color** (object) - Color option.
          - **value** (string) - Selected color value.
    - **preferences** (object) - Preferred variant options.
      - **color** (string) - Preferred color.
  - **bundleSeed** (boolean) - Indicates if this product is the seed for the bundle (present for seeded bundles).

#### Response Example
```json
[
  {
    "responseId": "3fe8efb5-791f-4cef-914e-90219132f9ae",
    "profile": { "tag": "cross-sell" },
    "results": [
      {
        "id": "52079546040686",
        "mappings": {
          "core": {
            "name": "Double fleece jacket",
            "price": 53,
            "sku": "PROD-12345",
            "imageUrl": "https://example.com/images/product.png",
            "available": true
          }
        },
        "variants": {
          "data": [
            {
              "mappings": { "core": { "uid": "52079546040686", "price": 103 } },
              "options": { "color": { "value": "Black" } }
            }
          ],
          "preferences": { "color": "Black" }
        },
        "bundleSeed": true 
      }
    ]
  }
]
```
```

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

### POST /{siteId}/recommendations/clickthrough

Source: https://docs.athoscommerce.com/reference/recommendations-tracking-guide

Call this endpoint when a shopper clicks on a recommended product or banner, navigating them to the Product Detail Page (PDP).

```APIDOC
## POST /{siteId}/recommendations/clickthrough

### Description
Tracks when a shopper clicks on a recommended product or banner. This event signifies user interest and potential conversion.

### Method
POST

### Endpoint
`/{siteId}/recommendations/clickthrough`

### Parameters
#### Path Parameters
- **siteId** (string) - Required - The ID of the website.

#### Request Body
- **context** (object) - Optional - See context guide for details.
- **data** (object) - Required
  - **tag** (string) - Required - Recommendation profile tag.
  - **responseId** (string) - Required - Unique ID from Recommendations API response.
  - **results** (array) OR **banners** (array) - Required - Exactly one clicked item. If it's a product, use the 'results' array. If it's a banner, use the 'banners' array.
    - **type** (string) - Required - Type of the item, e.g., "product".
    - **parentId** (string) - Required - Parent ID of the product.
    - **uid** (string) - Required - Unique ID of the product.

### Request Example
```json
{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### POST /components/examples/addtocart

Source: https://docs.athoscommerce.com/reference/search-addtocart

Endpoint to process adding items to the cart.

```APIDOC
## POST /components/examples/addtocart

### Description
Adds items to the shopping cart based on the provided context and product data.

### Method
POST

### Endpoint
/components/examples/addtocart

### Request Body
- **context** (object) - Required - Contains session, user, and page information.
- **data** (object) - Required - Contains the results of the items to be added.

### Request Example
{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0",
    "timestamp": "2006-01-02T15:04:05Z",
    "pageUrl": "https://imaginary.storefront.com/collections/shop?q=shirt&view=products",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "athos/custom/1.0",
    "currency": { "code": "USD" }
  },
  "data": {
    "responseId": "0217acd9-540c-48f3-bd6d-e23128e99fa8",
    "results": [
      { "parentId": "8128331911111", "uid": "8128331907370", "qty": 1, "price": 29.99 }
    ]
  }
}

### Response
#### Success Response (200)
- **success** (boolean) - Data sent and received

#### Response Example
{
  "success": true
}
```

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

### Invalid minimum value passed error example

Source: https://docs.athoscommerce.com/reference/login

Example of an error when the minimum value constraint is not met for a key, such as `context.currency.code` expecting a length of 3. The `data` field provides a structural hint.

```json
{
  "success": false,
  "error": "ValidationError",
  "messages": [
    "invalid minimum value passed for key `context.currency.code` - expected length `3`"
  ],
  "data": "{\n    \"context\": { /* varies by endpoint */},\n    \"data\": { */varies by endoint */ }"
}
```