canonical: https://jentic.com/apis/jirafe.com/jirafe

# Jirafe Events

The Jirafe Events API records ecommerce behavioral events for analytics. It accepts cart, order, product, category, and customer events for a given site, plus a batch endpoint that submits several events at once, feeding Jirafe's merchandising and product analytics. Each event posts as JSON scoped to one site, so an agent can stream shopper activity into Jirafe without wiring a full tracking SDK.

## For AI agents

Send cart, order, product, category, and customer events for a site to Jirafe for ecommerce analytics, individually or in batches.

## Scope

Does not build dashboards, run queries, or store product catalogs; use it to send ecommerce events to Jirafe only.

## Capabilities

- Record cart events as shoppers add or remove items
- Record order events when a purchase completes
- Record product view and detail events for a site
- Record category browsing events
- Record customer identification events
- Submit multiple events together through the batch endpoint

## Use cases

### Stream storefront events to analytics

Merchandising teams need shopper behavior in one analytics system to spot drop-off and demand. The Jirafe Events API accepts cart, product, category, and order events for a site, so a storefront can post each interaction as it happens and let Jirafe assemble funnels and product performance. Events are scoped per site by the identifier in the path.

Example prompt: Post a cart event to Jirafe each time a shopper adds a product, including the site identifier and item details.

### Capture completed purchases

Revenue reporting depends on reliable order data. The Jirafe order event carries the details of a completed purchase for a site, letting an analytics pipeline attribute revenue to sessions and campaigns without direct database access. Sending the event at checkout keeps the analytics view close to real time.

Example prompt: Send an order event to Jirafe when checkout completes, including the order total and line items for the site.

### Backfill history in bulk

Teams onboarding to analytics often have a backlog of events to load. The Jirafe batch endpoint accepts several events in one request, so an import job can replay historical cart, product, and order activity for a site rather than posting each event separately. Batching reduces the number of round trips during a migration.

Example prompt: Group a day of stored storefront events into a single batch request and post it to Jirafe for the site.

### Agent-driven event instrumentation

An AI agent managing a storefront integration can emit analytics events without a developer hand-wiring each call. Through Jentic the agent matches an intent such as 'record this cart event' to the right Jirafe operation, sends the payload for the site, and confirms acceptance. The OAuth2 credential stays in the user's Jentic One instance and never reaches the agent's prompt.

Example prompt: Translate a storefront webhook into a Jirafe cart or order event and post it for the correct site.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{siteId}/cart` | Record a cart event for a site. |
| POST | `/{siteId}/order` | Record an order event for a site. |
| POST | `/{siteId}/product` | Record a product view or detail event for a site. |
| POST | `/{siteId}/category` | Record a category browsing event for a site. |
| POST | `/{siteId}/customer` | Record a customer identification event for a site. |
| POST | `/{siteId}/batch` | Submit multiple events in a single batch for a site. |

## Key resources

- **Cart events** — Post cart add and update activity for a site.
- **Order events** — Post completed purchase details for a site.
- **Product and category events** — Post product view and category browsing activity for a site.
- **Customer events** — Post customer identification events for a site.
- **Batch** — Submit multiple events of any type in a single request.

## Why Jentic

- **Setup:** Wiring Jirafe yourself means running an OAuth2 flow, threading a site identifier into every event path, and shaping each cart, order, or product payload correctly. With Jentic you install once, import Jirafe from the API Directory, and authorize the credential a single time.
- **Permission scoping:** Jentic lets you grant your agent only the Jirafe event types it needs, such as cart and order events without customer events, and enforces that on every call.
- **Credential handling:** Your Jirafe OAuth2 credential is stored once, encrypted, by your own Jentic One instance. It is injected when a call runs and never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents find Jirafe through Jentic's intent search, matching a request like 'record this order event' to the right endpoint without hardcoded paths.

## Related APIs

- **Segment** — Customer data platform that collects and routes events to many tools.
- **Mixpanel** — Product analytics platform for event tracking, funnels, and retention.
- **Amplitude** — Product analytics for user journeys and behavioral cohorts.

## FAQ

### What can an AI agent do with the Jirafe Events API through Jentic?

An agent can post cart, order, product, category, and customer events for a site and submit several at once through the batch endpoint. Through Jentic the agent matches an intent to the right event operation and calls it with your OAuth2 credential injected at run time.

### How do I authenticate with the Jirafe Events API?

Jirafe uses OAuth2, so requests carry an access token obtained through the authorization flow. You authorize once and store the credential in your Jentic One instance, which supplies the token on each call rather than placing it in the agent's prompt.

### Are events scoped to a single store?

Yes. Every event endpoint takes a site identifier in its path, so each call records activity for one store. Send the identifier that matches the storefront the event came from.

### Does the API define rate limits for event ingestion?

The OpenAPI specification does not state rate limits or ingestion quotas; throughput depends on your Jirafe agreement. Confirm the limits that apply to your account with Jirafe before running a large backfill.

### Can I control what my agent is allowed to do with the Jirafe Events API?

Yes. Jentic lets you allow only the event types your agent should send, for example cart and order events while withholding customer events. Your Jentic One instance enforces that scope on every call and keeps the OAuth2 credential outside the agent's context.