> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bily.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bily glossary

> Clear definitions for Bily products, events, identity, analytics, API scope, and MCP operations.

## Products and surfaces

<AccordionGroup>
  <Accordion title="Bily">
    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.
  </Accordion>

  <Accordion title="Bily Apps">
    Bily's installable capability layer. You can review, configure, install, observe, update, or revoke an App through the website connection you already control.
  </Accordion>

  <Accordion title="Bily JavaScript SDK">
    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.
  </Accordion>

  <Accordion title="Bily API">
    A versioned HTTP interface for trusted server workflows. Authenticated endpoints expose Bily identity, stores, analytics, connected data, and supported actions.
  </Accordion>

  <Accordion title="Bily MCP">
    A Streamable HTTP interface for compatible AI clients. Its two stable tools, `search` and `execute`, expose current Bily operations.
  </Accordion>
</AccordionGroup>

## Events and payloads

<AccordionGroup>
  <Accordion title="Event">
    A named browser outcome with an optional payload. Examples include `PageView`, `Product Viewed`, `Order Completed`, and `workspace_created`.
  </Accordion>

  <Accordion title="Known event">
    An event name in `KnownBilyEvent`. TypeScript autocompletes known names, while the SDK also accepts custom non-empty strings.
  </Accordion>

  <Accordion title="Custom event">
    An application-specific event name from your code. Use stable snake\_case names. Put changing values in the payload.
  </Accordion>

  <Accordion title="Payload">
    The optional object passed to `track()`. It can include typed client, product, order, page, and search fields, plus reviewed custom properties.
  </Accordion>

  <Accordion title="event_id">
    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.
  </Accordion>

  <Accordion title="ts">
    The event timestamp. The SDK generates an ISO timestamp unless you provide `ts` as a string.
  </Accordion>

  <Accordion title="PageView">
    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.
  </Accordion>

  <Accordion title="Single-page application (SPA)">
    A browser application that changes routes without loading a new document. Its router integration sends an explicit `PageView` for each later route change.
  </Accordion>

  <Accordion title="Product">
    A `BilyProduct` with required `id`, `name`, `price`, and `currency`, plus optional quantity, SKU, category, brand, and image fields.
  </Accordion>

  <Accordion title="Order">
    A `BilyOrder` for one order. It can include products, currency, total, tax, discount, discount code, and shipping fees.
  </Accordion>
</AccordionGroup>

## Identity and acquisition

<AccordionGroup>
  <Accordion title="Bily browser tracking ID">
    The browser-context identifier from `getBilyTrackingId()`. It can persist in browser storage, but it is not an authenticated account ID or authorization value.
  </Accordion>

  <Accordion title="client.userId">
    Your stable authenticated customer or account ID on an event. It provides context. It does not log anyone in or prove authorization.
  </Accordion>

  <Accordion title="sourceUrl">
    The current page URL you include with an explicit event, especially an SPA page view.
  </Accordion>

  <Accordion title="referrer">
    An optional referring URL you include when your privacy policy permits it.
  </Accordion>

  <Accordion title="Attribution">
    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.
  </Accordion>
</AccordionGroup>

## Analytics and connected data

<AccordionGroup>
  <Accordion title="Conversions">
    Orders in Bily advertising analytics. Aggregate order volume with `sum(conversions)`.
  </Accordion>

  <Accordion title="People">
    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.
  </Accordion>

  <Accordion title="Sessions">
    Total 30-minute visits. Use `sum(sessions)` as the session denominator only when your selected rows contain the complete traffic population for that grouping.
  </Accordion>

  <Accordion title="Pageviews">
    Tracked page-view events. This is event volume, not unique visitors or sessions.
  </Accordion>

  <Accordion title="Conversion rate (CVR)">
    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.
  </Accordion>

  <Accordion title="Return on ad spend (ROAS)">
    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.
  </Accordion>

  <Accordion title="Cost per acquisition (CPA)">
    Spend divided by orders when orders are greater than zero. Bily reports use order volume—not customer count—for CPA.
  </Accordion>

  <Accordion title="Customer acquisition cost (CAC)">
    Spend divided by customers when the customer count is greater than zero. CAC differs from CPA whenever one customer places more than one order.
  </Accordion>

  <Accordion title="Customer lifetime value (LTV)">
    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.
  </Accordion>

  <Accordion title="Platform money">
    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.
  </Accordion>

  <Accordion title="Product orders">
    Product-order occurrences in the `product_metrics` dataset. Aggregate them with `sum(orders)`. Row count does not equal product-order count.
  </Accordion>

  <Accordion title="Units">
    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.
  </Accordion>

  <Accordion title="Connection">
    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.
  </Accordion>

  <Accordion title="Pixel">
    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.
  </Accordion>

  <Accordion title="Ad account">
    An advertising account mapped to a Bily store. A store connection exposes connected accounts. Enabled accounts are selected for Bily reads or supported actions.
  </Accordion>

  <Accordion title="Asset">
    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.
  </Accordion>

  <Accordion title="Data readiness">
    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.
  </Accordion>

  <Accordion title="Quality warning">
    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.
  </Accordion>
</AccordionGroup>

## Access and scope

<AccordionGroup>
  <Accordion title="Organization">
    The Bily team boundary that owns access. API and MCP requests verify that the authenticated identity can access the organization.
  </Accordion>

  <Accordion title="Store">
    A connected commerce or web property within an organization. Store-scoped API paths use the exact URL returned by Bily discovery.
  </Accordion>

  <Accordion title="Scope">
    The organizations, stores, permissions, and actions available to an authenticated identity or key.
  </Accordion>

  <Accordion title="Customer context">
    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.
  </Accordion>

  <Accordion title="API key">
    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.
  </Accordion>

  <Accordion title="Bily Connect">
    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.
  </Accordion>

  <Accordion title="Fallback key">
    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.
  </Accordion>

  <Accordion title="Request ID">
    A safe correlation value in the Bily API `x-request-id` response header. Save it when you diagnose an API failure.
  </Accordion>
</AccordionGroup>

## MCP operations

<AccordionGroup>
  <Accordion title="Operation catalog">
    The current set of Bily reads and actions discoverable through MCP `search`, including helper signatures, schemas, and planning guidance.
  </Accordion>

  <Accordion title="search">
    The MCP tool that matches your intent to current Bily operations. It accepts `query`, optional `storeUrl`, and an optional limit from 1 to 20.
  </Accordion>

  <Accordion title="execute">
    The MCP tool that runs a focused async arrow function with `bily.*` helpers. It returns a JSON-serializable `result` and captured `logs`.
  </Accordion>

  <Accordion title="Risk tier">
    Advisory MCP planning metadata, such as `read`, `draft_write`, `spend_affecting`, or `destructive`.
  </Accordion>

  <Accordion title="Approval policy">
    Advisory MCP planning metadata for the recommended review before a write or spend-affecting action. The client approval prompt remains the visible approval boundary.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="What is Bily?" icon="sparkles" href="/concepts/what-is-bily" />

  <Card title="Customer FAQ" icon="circle-question" href="/troubleshooting/faqs" />
</CardGroup>