Cart & Checkout Event HTTP APIs

You can call Alhena's APIs for cart and checkout events directly from your server, rather than using the JS 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.

Obtaining Fingerprints

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

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

{
  "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

{
  "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)

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

{
  "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

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

Error Codes

• MISSING_REQUIRED_FIELDS

• COMPANY_NOT_FOUND

• ACTIVE_TICKET_NOT_FOUND

• ORDER_ALREADY_EXISTS

Example (CURL)

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.