Skip to main content

​
Products and surfaces

The programmable customer data and activation layer for websites. It keeps browser, server, and AI workflows aligned to the same website, organization, and store context.
Bily’s installable capability layer. You can review, configure, install, observe, update, or revoke an App through the website connection you already control.
The @bilyai/js browser package. It installs the exact Bily tracking URL, queues early calls, sends known and custom events, and exports browser-safe TypeScript methods and types.
A versioned HTTP interface for trusted server workflows. Authenticated endpoints expose Bily identity, stores, analytics, connected data, and supported actions.
A Streamable HTTP interface for compatible AI clients. Its two stable tools, search and execute, expose current Bily operations.

​
Events and payloads

A named browser outcome with an optional payload. Examples include PageView, Product Viewed, Order Completed, and workspace_created.
An event name in KnownBilyEvent. TypeScript autocompletes known names, while the SDK also accepts custom non-empty strings.
An application-specific event name from your code. Use stable snake_case names. Put changing values in the payload.
The optional object passed to track(). It can include typed client, product, order, page, and search fields, plus reviewed custom properties.
The identifier for one logical outcome. The SDK generates it when missing. It supports correlation, but it is not an ingestion receipt or an exactly-once guarantee.
The event timestamp. The SDK generates an ISO timestamp unless you provide ts as a string.
Bily’s current page-view event name. The browser script records the initial document automatically. Single-page applications send it for each later committed route.
A browser application that changes routes without loading a new document. Its router integration sends an explicit PageView for each later route change.
A BilyProduct with required id, name, price, and currency, plus optional quantity, SKU, category, brand, and image fields.
A BilyOrder for one order. It can include products, currency, total, tax, discount, discount code, and shipping fees.

​
Identity and acquisition

The browser-context identifier from getBilyTrackingId(). It can persist in browser storage, but it is not an authenticated account ID or authorization value.
Your stable authenticated customer or account ID on an event. It provides context. It does not log anyone in or prove authorization.
The current page URL you include with an explicit event, especially an SPA page view.
An optional referring URL you include when your privacy policy permits it.
The link between observed customer activity and acquisition or advertising context. Use Bily’s returned analytics fields as the reporting contract. The SDK does not define a public first-touch or last-touch rule.

​
Analytics and connected data

Orders in Bily advertising analytics. Aggregate order volume with sum(conversions).
Unique browser visitors in Bily advertising analytics. Use sum(people) as the visitor denominator only when your selected rows contain the complete traffic population for that grouping.
Total 30-minute visits. Use sum(sessions) as the session denominator only when your selected rows contain the complete traffic population for that grouping.
Tracked page-view events. This is event volume, not unique visitors or sessions.
Orders divided by a complete traffic denominator. Visitor CVR is sum(conversions) / sum(people); session CVR is sum(conversions) / sum(sessions). Never use orders, revenue, customers, purchase-only sessions, or conversion-filtered rows as the denominator.
Revenue divided by spend when spend is greater than zero. Bily’s normalized channel and asset reports use the report’s revenue and store-currency-normalized spend. Raw platform revenue and spend remain separate where available.
Spend divided by orders when orders are greater than zero. Bily reports use order volume—not customer count—for CPA.
Spend divided by customers when the customer count is greater than zero. CAC differs from CPA whenever one customer places more than one order.
A customer’s total lifetime revenue in the customer_ltv dataset. Average LTV is the average customer total_revenue. Net LTV subtracts customer refunds where available. This is lifetime customer data, not period new-versus-returning revenue.
Raw fields such as p_spend stay in the ad account’s native p_currency. Group raw money aggregates by p_currency. For store-currency spend and efficiency across accounts, use normalized channel or asset reports.
Product-order occurrences in the product_metrics dataset. Aggregate them with sum(orders). Row count does not equal product-order count.
Product quantity in the product_metrics dataset. Aggregate it with sum(units). Units exceed product orders when an order contains more than one unit of a product.
A store-scoped link to a supported data or activation surface. Depending on the operation, Bily can expose tracking connections, catalog sync connections, connected advertising accounts, and enabled account selections.
The public API resource for a store-scoped tracking connection. Its record includes an ID, name, channel, enabled state, settings, timestamps, and optional publish state.
An advertising account mapped to a Bily store. A store connection exposes connected accounts. Enabled accounts are selected for Bily reads or supported actions.
A normalized campaign, ad set, or ad from an enabled ad account. Results identify the platform, account, asset type and ID, status, available budget fields, and fields Bily currently supports writing.
A store’s per-platform connector and account-selection status. It tells you whether to connect a source, select accounts, or wait before using the data.
Analytics guidance with a code, severity, message, evidence, and recommended next step. Investigate review_required results and blocking warnings before they influence channel, budget, creative, or attribution decisions.

​
Access and scope

The Bily team boundary that owns access. API and MCP requests verify that the authenticated identity can access the organization.
A connected commerce or web property within an organization. Store-scoped API paths use the exact URL returned by Bily discovery.
The organizations, stores, permissions, and actions available to an authenticated identity or key.
The authenticated Bily user, accessible organizations, and their stores. GET /context and bily.context() return this shape in one request, filtered to the connection’s allowed scope.
A server-side credential for the Bily API. A key created for a selected store carries that store and organization scope. Keep it in secret storage. Never expose it in browser code, prompts, logs, or repositories.
The recommended MCP sign-in path for compatible clients. It uses Bily’s OAuth flow and the signed-in user’s current organization and store memberships.
A one-time-revealed access key for MCP clients that cannot complete Bily Connect. A key created for a selected store gives MCP that default store and organization scope.
A safe correlation value in the Bily API x-request-id response header. Save it when you diagnose an API failure.

​
MCP operations

The current set of Bily reads and actions discoverable through MCP search, including helper signatures, schemas, and planning guidance.
The MCP tool that matches your intent to current Bily operations. It accepts query, optional storeUrl, and an optional limit from 1 to 20.
The MCP tool that runs a focused async arrow function with bily.* helpers. It returns a JSON-serializable result and captured logs.
Advisory MCP planning metadata, such as read, draft_write, spend_affecting, or destructive.
Advisory MCP planning metadata for the recommended review before a write or spend-affecting action. The client approval prompt remains the visible approval boundary.

What is Bily?

Customer FAQ