Browser Session Purchases
Octocom can record purchases made by users during their browser session. This lets you tie checkout events to the same visitor who may have chatted with your AI — useful for analytics, attribution, and support. Recording purchases is done via a public API that needs no API key: a per-session purchase token proves the purchase comes from the visitor's own session.
For Shopify stores, connecting or reconnecting the Octocom app automatically activates checkout tracking. You do not need to implement the API integration below. See Shopify revenue tracking for consent and browser-session requirements. The Metrics -> Sales tab is available to everyone with metrics access, regardless of ecommerce platform.
What is a browser session?
When a visitor opens the Octocom chat widget, it creates a browser session. The session is identified by a UUID and is stored in the visitor's localStorage, so it persists across page navigations and later visits within the same browser. Nothing is stored and no session is created for a visitor who never opens the chat, so those visits have no session ID to report a purchase against.
A browser session is how Octocom links activity across a visitor's journey: it connects chat conversations, page visits, and (with this integration) purchases to a single anonymous visitor profile.
Prerequisites
Before you record purchases via the API, make sure you have:
- ✅ The Octocom chat widget installed on your site
Getting the browser session ID
The browser session ID is stored in localStorage under the key:
octocom-browser-session-id:{configId}where {configId} is your web chat configuration ID (visible in the Octocom dashboard under Settings → Channels → Web Chat). The value is the session UUID itself — read it verbatim and send it as-is.
If you don't know your configId, you can find the session ID by scanning localStorage for any key with the octocom-browser-session-id: prefix:
function getOctocomBrowserSessionId() {
for (let i = 0; i < localStorage.length; i++) {
const key = localStorage.key(i);
if (key?.startsWith("octocom-browser-session-id:")) {
return localStorage.getItem(key);
}
}
return null;
}
const browserSessionId = getOctocomBrowserSessionId();This returns null if the widget script has not run yet, or if the visitor has never opened the chat in this browser. In private/incognito windows the session still exists for the duration of the tab — it just won't carry over once the tab is closed.
Without a valid browser session ID, the API returns 404 Browser session not found. The purchase is not stored.
Getting the purchase token
The chat widget also stores a purchase token for the session under:
octocom-purchase-token:{browserSessionId}Send it as purchaseToken with the purchase. It proves the purchase comes from the visitor's own session, so nobody who only knows a session ID can add purchases to your revenue metrics. It authorizes nothing else, so it is safe to use in checkout code. Never send the separate octocom-session-credential: value.
const purchaseToken = localStorage.getItem(
`octocom-purchase-token:${browserSessionId}`,
);Purchases sent without a valid token are still recorded for now, but marked unverified. A later release will stop counting unverified purchases toward attributed revenue, so add the token to your integration now. Visitors whose widget has not loaded since this change may not have a token yet; the widget stores one the next time it loads.
Recording a purchase via the API
Endpoint
POST https://api.octocom.ai/rest/v1/browser-sessions/:browserSessionId/purchases- No authentication is required; the endpoint is protected by rate limiting only.
- Rate limit: Maximum 100 requests per minute per IP address. Exceeding this returns 429 with an error message.
Example
const browserSessionId = getOctocomBrowserSessionId(); // see above
if (browserSessionId) {
try {
const response = await fetch(
`https://api.octocom.ai/rest/v1/browser-sessions/${browserSessionId}/purchases`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
lineItems: [
{
id: "product-123",
quantity: 2,
},
{
id: "product-456",
quantity: 1,
variant: { variantId: "variant-789" },
},
],
totalPrice: 99.99,
currencyCode: "USD",
provider: "shopify",
orderId: "1042",
purchaseToken: localStorage.getItem(
`octocom-purchase-token:${browserSessionId}`,
),
}),
},
);
if (!response.ok) {
console.error(
"Failed to record purchase",
response.status,
await response.text(),
);
}
} catch (err) {
console.error("Failed to record purchase", err);
}
}Full checkout integration example
Here is a complete example of how you might call this at the end of a checkout flow:
async function recordOctocomPurchase({
lineItems,
totalPrice,
currencyCode,
provider,
orderId,
}) {
function getOctocomBrowserSessionId() {
for (let i = 0; i < localStorage.length; i++) {
const key = localStorage.key(i);
if (key?.startsWith("octocom-browser-session-id:")) {
return localStorage.getItem(key);
}
}
return null;
}
const browserSessionId = getOctocomBrowserSessionId();
if (!browserSessionId) {
// Widget hasn't initialised yet or Octocom isn't installed — skip silently.
return;
}
try {
const response = await fetch(
`https://api.octocom.ai/rest/v1/browser-sessions/${browserSessionId}/purchases`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
lineItems,
totalPrice,
currencyCode,
provider,
orderId,
purchaseToken: localStorage.getItem(
`octocom-purchase-token:${browserSessionId}`,
),
}),
},
);
if (!response.ok) {
console.error(
"Octocom: failed to record purchase",
response.status,
await response.text(),
);
}
} catch (err) {
console.error("Octocom: failed to record purchase", err);
}
}
// Call this after a successful checkout:
recordOctocomPurchase({
lineItems: [
{ id: "product-123", quantity: 2 },
{ id: "product-456", quantity: 1, variant: { variantId: "variant-789" } },
],
totalPrice: 99.99,
currencyCode: "USD",
provider: "shopify",
orderId: "1042",
});Request schema
The request body must be valid JSON with the following shape:
{
lineItems: Array<{
id: string, // Required. The purchased item's (product) ID.
quantity: number, // Required. Quantity purchased.
variant?: { // Optional. Include only when the item is a variant.
variantId: string, // The variant's ID.
},
// You may include other fields; they are stored as JSON.
}>,
totalPrice: number, // Required. Total price of the purchase. Must be positive.
currencyCode: string, // Required. e.g. "USD", "EUR".
provider?: string, // Optional. e.g. "shopify", "api". Default: "api".
orderId?: string, // Optional. Your own order identifier, used for reconciliation. Any string you choose.
purchaseToken?: string, // Recommended. Read from localStorage `octocom-purchase-token:{browserSessionId}`.
}Line items:
lineItemsmust be an array. Each element represents one purchased item.- Each item must include:
id— the purchased product/item ID.quantity— how many of this item were purchased.
- If the item is a variant (e.g. size/color), add a
variantobject with avariantIdfield.
Example for a simple product and a variant product:
lineItems: [
{ id: "prod_abc", quantity: 2 },
{ id: "prod_xyz", quantity: 1, variant: { variantId: "var_123" } },
];Order ID:
orderIdis optional and accepts any string you choose — for example your store's order number ("1042","#1042") or the platform's order ID ("order_abc123","gid://shopify/Order/123"). It is stored as-is so you can later reconcile chatbot-attributed sessions against orders in your own system.- If you omit it, the purchase is still recorded — you just won't have a direct link back to your order record.
- Sending the same
orderIdagain for the same session does not record the order twice. The API returns the existing record.
Response
| Status | Meaning |
|---|---|
| 201 | Purchase recorded. Response body includes success: true, message, and id (UUID of the created purchase record). |
| 400 | Invalid request body (e.g. validation failed). |
| 404 | Browser session not found. Check that browserSessionId is a valid, existing session UUID. |
| 429 | Rate limit exceeded. Maximum 100 requests per minute per IP, or 60 purchases without a valid token per browser session per hour. |
| 500 | Server error (e.g. failed to store the purchase). |
Security considerations
- No API keys: This endpoint is intended to be called from the browser (e.g. after checkout). Because the URL and payload can be seen in client-side code, the endpoint does not use API keys. Instead, the
purchaseTokenproves the purchase comes from the visitor's own session, and rate limits apply (100 requests/minute per IP, 60 purchases without a valid token per hour per session). - Abuse: If you see abuse or spam purchases, report it to Octocom. We can help with additional mitigations (e.g. stricter limits or custom rules).
- CORS: The API is configured to allow requests from your origins as needed for browser-based calls.
Summary
| What you need | Description |
|---|---|
| Browser session ID | Read from localStorage using the key octocom-browser-session-id:{configId}, or scan for any key with the octocom-browser-session-id: prefix. |
| Line items | Array of objects with id, quantity, and optional variant: { variantId } for variants. |
| totalPrice / currencyCode | Total amount and currency of the order. |
| provider | Optional identifier (e.g. "shopify", "api") for where the purchase originated. |
| orderId | Optional. Any string identifying the order in your own system (e.g. "1042", "order_abc123"). Used for reconciliation. |
| purchaseToken | Recommended. Read from localStorage key octocom-purchase-token:{browserSessionId}. Purchases without it are marked unverified. |
Call POST …/browser-sessions/:browserSessionId/purchases with the above body to record a purchase for that session.