> 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 -**
* **EU -**
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://alhena.gitbook.io/docs/developer-reference/website-sdk/cart-checkout-events/http-apis.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.