> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/developer-reference/website-sdk/cart-checkout-events/http-apis.md).

# HTTP APIs

Alhena provides two HTTP endpoints so you can record cart and checkout events either via our Chat Widget SDK or directly from your own server‑side code. Recorded events will surface in **Analytics > Revenue impact** in the Alhena dashboard, attributing revenue back to sessions that interacted with the chat widget or Product FAQs.

Every request **must** include your `company_key` and the visitor’s fingerprints.

{% hint style="info" %}
NOTE: If you are using Shopify, the cart and checkout events are recorded by default and you do not need to follow these steps. You only need to manually report cart and checkout events for non-Shopify platforms.
{% endhint %}

### Obtaining Fingerprints

When using the Chat Widget on the browser, you can retrieve the visitor identifiers with:

```js
const fp            = window.gleenWidget.getFingerprint();
const faqFp         = window.gleenWidget.getFAQFingerprint();
```

If you call these HTTP APIs from your server side, you must pass the same fingerprint values you generated or stored during the user’s session.

## Base URL

All Analytics API requests should be sent to the region‑appropriate host:

* **US region -** <https://app.alhena.ai/>
* **EU -** <https://eu.alhena.ai/>

Choose the endpoint that matches your organization’s region when constructing your HTTP calls. All other paths (e.g. `/cart_events`, `/checkout_events`) remain the same.\`\`\`

## 1. Record a Cart Event

### **Endpoint**

```
POST /analytics/cart_events
```

### **Payload**

```json
{
  "company_key":            "gleen",
  "user_fingerprint":       "550e8400-e29b-41d4-a716-446655440000",
  "user_faq_fingerprint":   "660e8400-e29b-41d4-a716-446655441111",
  "type":                   "ITEM_ADDED",
  "product_id":             "123",
  "product_name":           "Product 1",
  "value":                  100,
  "currency":               "USD",
  "quantity":               1,
  "source":                 "SHOPIFY"
}
```

| Field                  | Type   | Required | Description                                                                      |
| ---------------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `company_key`          | string | Yes      | Your Alhena company key                                                          |
| `user_fingerprint`     | string | Yes      | Visitor fingerprint (UUID)                                                       |
| `user_faq_fingerprint` | string | Yes      | FAQ widget fingerprint (UUID)                                                    |
| `type`                 | string | Yes      | `"ITEM_ADDED"`, `"QUANTITY_INCREASED"`, `"QUANTITY_DECREASED"`, `"ITEM_REMOVED"` |
| `product_id`           | string | Yes      | Internal product identifier                                                      |
| `product_name`         | string | Yes      | Human‑readable product name                                                      |
| `value`                | number | Yes      | Price after discounts                                                            |
| `currency`             | string | Yes      | ISO 4217 code (e.g. `"USD"`)                                                     |
| `quantity`             | number | Yes      | Quantity after this event                                                        |

### Success Response

```json
{
  "status": "success",
  "event_type": "CART_EVENT_RECORDED"
}
```

### Error Codes

* `MISSING_REQUIRED_FIELDS`
* `COMPANY_NOT_FOUND`
* `ACTIVE_TICKET_NOT_FOUND`
* `PREVIOUS_ITEM_ADDED_EVENT_NOT_FOUND`
* `PREVIOUS_QUANTITY_INCREASED_EVENT_NOT_FOUND`

### Example (CURL)

```bash
curl https://app.alhena.ai/analytics/cart_events \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "company_key": "gleen",
    "user_fingerprint": "550e8400-e29b-41d4-a716-446655440000",
    "user_faq_fingerprint": "660e8400-e29b-41d4-a716-446655441111",
    "type": "ITEM_ADDED",
    "product_id": "123",
    "product_name": "Product 1",
    "value": 100,
    "currency": "USD",
    "quantity": 1,
    "source": "CUSTOM"
  }'
```

## 2. Record a Checkout Event

### **Endpoint**

```
POST /analytics/checkout_events
```

### Payload

```json
{
  "company_key":            "gleen",
  "user_fingerprint":       "550e8400-e29b-41d4-a716-446655440000",
  "user_faq_fingerprint":   "660e8400-e29b-41d4-a716-446655441111",
  "value":                  100,
  "currency":               "USD",
  "orderId":                "123", // optional
  "line_items": [
    {
      "product_id":         "123",
      "product_name":       "Product 1",
      "quantity":           1,
      "value":              100,
      "currency":           "USD"
    }
  ]
}
```

| Field                  | Type   | Required | Description                             |
| ---------------------- | ------ | -------- | --------------------------------------- |
| `company_key`          | string | Yes      | Your Alhena company key                 |
| `user_fingerprint`     | string | Yes      | Visitor fingerprint (UUID)              |
| `user_faq_fingerprint` | string | Yes      | FAQ widget fingerprint (UUID)           |
| `value`                | number | Yes      | Total order value after discounts/taxes |
| `currency`             | string | Yes      | ISO 4217 code                           |
| `orderId`              | string | No       | Your unique internal order identifier   |
| `line_items`           | array  | Yes      | Array of purchased items (see below)    |

Each item in `line_items`:

| Field          | Type   | Required | Description                        |
| -------------- | ------ | -------- | ---------------------------------- |
| `product_id`   | string | Yes      | Internal product identifier        |
| `product_name` | string | Yes      | Human‑readable product name        |
| `quantity`     | number | Yes      | Quantity purchased                 |
| `value`        | number | Yes      | Line‑item total (price × quantity) |
| `currency`     | string | Yes      | ISO 4217 code                      |

### Success Response

```json
{
  "status": "success",
  "event_type": "CHECKOUT_EVENT_RECORDED"
}
```

### Error Codes

* `MISSING_REQUIRED_FIELDS`
* `COMPANY_NOT_FOUND`
* `ACTIVE_TICKET_NOT_FOUND`
* `ORDER_ALREADY_EXISTS`

### Example (CURL)

```bash
curl https://app.alhena.ai/analytics/checkout_events \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "company_key": "gleen",
    "user_fingerprint": "550e8400-e29b-41d4-a716-446655440000",
    "user_faq_fingerprint": "660e8400-e29b-41d4-a716-446655441111",
    "value": 199.97,
    "currency": "USD",
    "order_id": "ORD-7890",
    "line_items": [
      {
        "product_id": "123",
        "product_name": "Product 1",
        "quantity": 2,
        "value": 199.97,
        "currency": "USD"
      }
    ]
  }'
```

***

## Notes & Troubleshooting

* **Session requirement**\
  Events are only recorded if the visitor has interacted with the **chat widget** or **Product FAQs** in that session.
* **Visibility**\
  View attributed cart and purchase revenue under **Analytics > Revenue impact** in the Alhena dashboard.
* **Server‑side calls**\
  If you call these endpoints from your backend, be sure to capture and store the visitor’s `getFingerprint()` / `getFAQFingerprint()` values during the user’s session.
* **Validation errors**\
  Inspect the JSON error response for codes and adjust your payload accordingly.