# Bily developer docs

> Connect website data to Bily, activate Bily Apps, and build trusted browser, server, and AI workflows.

## Docs

- [Event names](https://docs.bily.ai/api-reference/events.md): Review known Bily event names, custom event support, and normalized compatibility aliases.
- [getBilyTrackingId()](https://docs.bily.ai/api-reference/get-bily-tracking-id.md): Read or create the stable Bily browser identifier.
- [init()](https://docs.bily.ai/api-reference/init.md): Initialize Bily with an exact script URL and configure loading behavior.
- [SDK overview](https://docs.bily.ai/api-reference/overview.md): Review the public methods and TypeScript types exported by @bilyai/js.
- [Payload types](https://docs.bily.ai/api-reference/payload.md): Review BilyPayload, client, address, product, and order fields exported by @bilyai/js.
- [ready()](https://docs.bily.ai/api-reference/ready.md): Wait for Bily to finish loading when you need an explicit installation check.
- [track()](https://docs.bily.ai/api-reference/track.md): Send a known Bily event or a custom application event with an optional payload.
- [Bily Apps](https://docs.bily.ai/concepts/bily-apps.md): Install capabilities, not scripts, through Bily's governed website connection.
- [Bily glossary](https://docs.bily.ai/concepts/glossary.md): Definitions for Bily products, browser events, identity, API scoping, and MCP operations.
- [What is Bily?](https://docs.bily.ai/concepts/what-is-bily.md): Understand Bily's programmable customer data and activation layer across browser, server, and AI workflows.
- [Choose the API or MCP](https://docs.bily.ai/guides/api-mcp-selection.md): Choose the Bily API for deterministic software workflows and Bily MCP for compatible AI-client work.
- [Client data](https://docs.bily.ai/guides/client-data.md): Attach approved customer and account context to individual Bily events.
- [Custom events](https://docs.bily.ai/guides/custom-events.md): Track stable application-specific event names and properties with @bilyai/js.
- [Ecommerce events](https://docs.bily.ai/guides/ecommerce.md): Track products, carts, checkouts, and orders with Bily's typed ecommerce payloads.
- [Event and data model](https://docs.bily.ai/guides/event-data-model.md): Design stable Bily event names, payloads, products, orders, and custom properties.
- [Identity and attribution](https://docs.bily.ai/guides/identity-attribution.md): Use Bily browser IDs, authenticated user context, and acquisition fields without overstating identity or attribution behavior.
- [Plan a Bily implementation](https://docs.bily.ai/guides/implementation-planning.md): Turn business outcomes into a scoped Bily event plan, ownership model, and release checklist before writing code.
- [Page views](https://docs.bily.ai/guides/pageviews.md): Capture one automatic initial page view and explicit page views for later SPA routes.
- [Privacy and governance](https://docs.bily.ai/guides/privacy-governance.md): Govern Bily event fields, browser identity, credentials, approvals, and production changes.
- [Roll out Bily to production](https://docs.bily.ai/guides/production-rollout.md): Release Bily browser, API, and MCP work in stages with explicit checks and rollback criteria.
- [Validate and debug an implementation](https://docs.bily.ai/guides/validation-debugging.md): Prove Bily loading, event behavior, payloads, API requests, and MCP operations with focused evidence.
- [Verify your installation](https://docs.bily.ai/guides/verification.md): Confirm Bily loads once, records the initial page view, and tracks later events without duplicates.
- [Bily developer documentation](https://docs.bily.ai/index.md): Connect website data to Bily and build trusted browser, server, and AI workflows.
- [MCP authentication and scoping](https://docs.bily.ai/mcp/authentication.md): Understand Bily Connect, access key fallback, and server-enforced organization and store boundaries.
- [MCP client configuration](https://docs.bily.ai/mcp/client-configuration.md): Configure a Streamable HTTP MCP client for Bily Connect or a store-scoped access key.
- [MCP examples](https://docs.bily.ai/mcp/examples.md): Discover Bily operations, run scoped reads, and prepare verifiable actions.
- [Bily MCP overview](https://docs.bily.ai/mcp/overview.md): Connect compatible AI clients to scoped Bily analytics, store data, and supported actions.
- [MCP quickstart](https://docs.bily.ai/mcp/quickstart.md): Connect Codex to Bily MCP, sign in through Bily Connect, and discover your first operation.
- [MCP safety and permissions](https://docs.bily.ai/mcp/safety.md): Use Bily MCP with explicit scope, client approval, focused execution, and post-action verification.
- [MCP tools and operations](https://docs.bily.ai/mcp/tools.md): Use Bily MCP search and execute, inspect planning guidance, and choose current Bily operations.
- [MCP troubleshooting](https://docs.bily.ai/mcp/troubleshooting.md): Resolve Bily MCP connection, authentication, scope, search, execution, and action errors.
- [Migrate to 2.0](https://docs.bily.ai/migrations/2-0.md): Prepare an existing @bilyai/js integration for the 2.0 initialization, readiness, payload, and event contract.
- [Data safety](https://docs.bily.ai/privacy/data-safety.md): Protect customer data and keep secrets out of browser tracking payloads.
- [Quickstart](https://docs.bily.ai/quickstart.md): Install Bily with the raw browser script or the JavaScript SDK, then verify event delivery.
- [API authentication](https://docs.bily.ai/rest-api/authentication.md): Create and use a Bily API key without exposing it in browser code, logs, or repositories.
- [Errors and request IDs](https://docs.bily.ai/rest-api/errors.md): Handle Bily API status codes, structured error bodies, retries, and request IDs safely.
- [Bily API overview](https://docs.bily.ai/rest-api/overview.md): Use the Bily API to access organization-scoped stores, analytics, integrations, and supported actions.
- [API quickstart](https://docs.bily.ai/rest-api/quickstart.md): Discover the authenticated user, organization, and store in one Bily API request.
- [Organizations and store scoping](https://docs.bily.ai/rest-api/scoping.md): Keep every Bily API request inside the intended organization and store boundary.
- [List analytics datasets](https://docs.bily.ai/rest-reference/analytics-sql/list-analytics-datasets.md): Lists the store-scoped datasets, required filters, available columns, and example SQL accepted by the query endpoint.
- [Run a scoped analytics query](https://docs.bily.ai/rest-reference/analytics-sql/run-a-scoped-analytics-query.md): Runs one read-only SQL query against a selected Bily dataset. Bily applies the authenticated store scope before the SQL runs.
- [Enrich advertising asset IDs](https://docs.bily.ai/rest-reference/analytics/enrich-advertising-asset-ids.md): Resolves supplied campaign, ad set, and ad IDs to names and statuses within one store and channel.
- [Get a customer lifetime value summary](https://docs.bily.ai/rest-reference/analytics/get-a-customer-lifetime-value-summary.md): Returns zero or one store-scoped summary row with customer, order, revenue, refund, value-window, and purchase-cadence totals.
- [Get a prepared channel summary](https://docs.bily.ai/rest-reference/analytics/get-a-prepared-channel-summary.md): Returns decision-ready channel rows and canonical totals for a date range. A 409 response means the requested range does not have complete prepared coverage.
- [Get a prepared daily series](https://docs.bily.ai/rest-reference/analytics/get-a-prepared-daily-series.md): Returns a daily, store-currency metric series with explicit date coverage and confidence metadata.
- [Get advertising overview](https://docs.bily.ai/rest-reference/analytics/get-advertising-overview.md): Returns current and previous period spend, revenue, conversions, AOV, MER, currency, and data reliability.
- [Get cohort metrics](https://docs.bily.ai/rest-reference/analytics/get-cohort-metrics.md): Returns monthly retention and cumulative revenue metrics for customer cohorts.
- [Get country metrics](https://docs.bily.ai/rest-reference/analytics/get-country-metrics.md): Returns attributed performance grouped by country and region.
- [Get customer lifetime value](https://docs.bily.ai/rest-reference/analytics/get-customer-lifetime-value.md): Returns store-scoped customer lifetime value, order cadence, attribution, and recency rows.
- [Get device metrics](https://docs.bily.ai/rest-reference/analytics/get-device-metrics.md): Returns attributed performance grouped by device, with optional operating system and browser detail.
- [Get prepared asset performance](https://docs.bily.ai/rest-reference/analytics/get-prepared-asset-performance.md): Returns decision-ready performance rows at campaign, ad set, or ad level. A 409 response means the requested range does not have complete prepared coverage.
- [Get product metadata](https://docs.bily.ai/rest-reference/analytics/get-product-metadata.md): Returns titles and image URLs for up to 200 comma-separated product IDs.
- [Get product metrics](https://docs.bily.ai/rest-reference/analytics/get-product-metrics.md): Returns attributed orders, units, revenue, and product context for the selected date range.
- [List available dimension values](https://docs.bily.ai/rest-reference/analytics/list-available-dimension-values.md): Returns countries, device types, operating systems, browsers, and product IDs available for filters.
- [Query advertising metrics](https://docs.bily.ai/rest-reference/analytics/query-advertising-metrics.md): Returns normalized advertising and attribution rows for the selected store and date range.
- [Clone a LinkedIn campaign group](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-linkedin-campaign-group.md): Clones a campaign group in a connected LinkedIn account. The clone uses a safe non-active status unless ACTIVE is explicit.
- [Clone a Meta ad](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-meta-ad.md): Clones an ad and its creative reference into a target ad set. The clone defaults to paused unless ACTIVE is explicit.
- [Clone a Meta ad set](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-meta-ad-set.md): Clones an ad set into the same or another campaign. The clone defaults to paused unless ACTIVE is explicit.
- [Clone a Microsoft campaign](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-microsoft-campaign.md): Clones a campaign in a connected Microsoft Ads account. The clone defaults to paused unless ACTIVE is explicit.
- [Clone a Pinterest campaign](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-pinterest-campaign.md): Clones a campaign in a connected Pinterest account. The clone defaults to paused unless ACTIVE is explicit.
- [Clone a Snapchat campaign](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-snapchat-campaign.md): Clones a campaign in a connected Snapchat account. The clone defaults to paused unless ACTIVE is explicit.
- [Clone a TikTok campaign](https://docs.bily.ai/rest-reference/campaign-actions/clone-a-tiktok-campaign.md): Clones a campaign in a connected TikTok account. The clone defaults to paused unless ACTIVE is explicit.
- [Create a Google campaign](https://docs.bily.ai/rest-reference/campaign-actions/create-a-google-campaign.md): Creates a campaign for a connected Google Ads account. The payload uses the account's supported campaign contract.
- [Create a LinkedIn campaign group](https://docs.bily.ai/rest-reference/campaign-actions/create-a-linkedin-campaign-group.md): Creates a campaign group for a connected LinkedIn account. New groups use a safe non-active status unless ACTIVE is explicit.
- [Create a Meta campaign](https://docs.bily.ai/rest-reference/campaign-actions/create-a-meta-campaign.md): Creates a campaign for a connected Meta account. New campaigns default to paused unless ACTIVE is explicit.
- [Create a Pinterest campaign](https://docs.bily.ai/rest-reference/campaign-actions/create-a-pinterest-campaign.md): Creates a campaign for a connected Pinterest account. New campaigns default to paused unless ACTIVE is explicit.
- [Create a Snapchat campaign](https://docs.bily.ai/rest-reference/campaign-actions/create-a-snapchat-campaign.md): Creates a campaign for a connected Snapchat account. New campaigns default to paused unless ACTIVE is explicit.
- [Create a TikTok campaign](https://docs.bily.ai/rest-reference/campaign-actions/create-a-tiktok-campaign.md): Creates a campaign for a connected TikTok account. New campaigns default to paused unless ACTIVE is explicit.
- [Read a Shopify REST resource](https://docs.bily.ai/rest-reference/commerce/read-a-shopify-rest-resource.md): Runs a store-scoped, read-only Shopify Admin REST request. Prefer GraphQL for new workflows.
- [Run a Shopify GraphQL operation](https://docs.bily.ai/rest-reference/commerce/run-a-shopify-graphql-operation.md): Runs a store-scoped Shopify Admin GraphQL query. Queries are enabled by default. Mutations require allowMutation=true and should receive an explicit user approval before the request.
- [Get platform support](https://docs.bily.ai/rest-reference/connections/get-platform-support.md): Returns connected accounts and the exact supported reads and actions available for the store.
- [List advertising assets](https://docs.bily.ai/rest-reference/connections/list-advertising-assets.md): Lists normalized campaigns, ad sets, and ads for enabled accounts in the store.
- [Get a customer journey](https://docs.bily.ai/rest-reference/customer-journeys/get-a-customer-journey.md): Returns one customer's ordered touchpoints for a date range. Treat the result as journey evidence; do not infer purchase or revenue facts unless the response explicitly includes them.
- [Get customer context](https://docs.bily.ai/rest-reference/identity/get-customer-context.md): Returns the authenticated user with accessible organizations and their nested stores in one request. A store-scoped API key is narrowed automatically; use organizationId only to explicitly select an accessible organization.
- [Get the authenticated identity](https://docs.bily.ai/rest-reference/identity/get-the-authenticated-identity.md): Returns the user attached to the API key and the active organization ID when a session supplies one.
- [List organizations](https://docs.bily.ai/rest-reference/identity/list-organizations.md): Lists every Bily organization available to the authenticated identity.
- [Get a store profile](https://docs.bily.ai/rest-reference/store-data/get-a-store-profile.md): Returns the current Bily profile and setup data for an accessible store.
- [Get data readiness](https://docs.bily.ai/rest-reference/store-data/get-data-readiness.md): Returns connection and account-selection readiness for the store's supported data and actions.
- [Get Meta signal quality](https://docs.bily.ai/rest-reference/store-data/get-meta-signal-quality.md): Returns the latest store-scoped event match summary and diagnostic breakdown.
- [Get Pinterest signal quality](https://docs.bily.ai/rest-reference/store-data/get-pinterest-signal-quality.md): Returns the latest store-scoped conversion quality diagnostics.
- [List catalog connections](https://docs.bily.ai/rest-reference/store-data/list-catalog-connections.md): Returns catalog synchronization connections configured for the store.
- [List managed ad accounts](https://docs.bily.ai/rest-reference/store-data/list-managed-ad-accounts.md): Returns the connected advertising accounts visible to the authenticated identity for the store.
- [List stores](https://docs.bily.ai/rest-reference/stores/list-stores.md): Lists stores in the selected organization.
- [Synchronize advertising accounts](https://docs.bily.ai/rest-reference/supported-actions/synchronize-advertising-accounts.md): Refreshes enabled advertising connections and their account metadata. Omit platforms to synchronize all enabled connections.
- [Update an advertising asset](https://docs.bily.ai/rest-reference/supported-actions/update-an-advertising-asset.md): Updates supported name, status, or budget fields. Read platform support and the asset's supportedWrites before submitting a change.
- [Create a tracking connection](https://docs.bily.ai/rest-reference/tracking-connections/create-a-tracking-connection.md): Creates a store-scoped tracking connection and synchronizes the current Bily configuration.
- [Delete a tracking connection](https://docs.bily.ai/rest-reference/tracking-connections/delete-a-tracking-connection.md): Removes a tracking connection from the store.
- [Enable or disable a tracking connection](https://docs.bily.ai/rest-reference/tracking-connections/enable-or-disable-a-tracking-connection.md): Changes the enabled state of an existing store-scoped tracking connection.
- [List tracking connections](https://docs.bily.ai/rest-reference/tracking-connections/list-tracking-connections.md): Returns store-scoped tracking connections without credential secrets.
- [Update a tracking connection](https://docs.bily.ai/rest-reference/tracking-connections/update-a-tracking-connection.md): Updates the public identifier, name, channel, enabled state, or supported settings for a connection.
- [HTML](https://docs.bily.ai/sdk/html.md): Install the exact Bily browser script on a plain HTML website.
- [JavaScript](https://docs.bily.ai/sdk/javascript.md): Install @bilyai/js in a browser application and track later client-side routes.
- [Next.js](https://docs.bily.ai/sdk/nextjs.md): Install Bily in a Next.js App Router application with one client component.
- [React](https://docs.bily.ai/sdk/react.md): Initialize Bily once in React and track later router transitions without duplicating the initial page view.
- [Troubleshooting](https://docs.bily.ai/troubleshooting.md): Resolve Bily loading errors, changed URLs, duplicate page views, missing SPA routes, and payload issues.
- [Frequently asked questions](https://docs.bily.ai/troubleshooting/faqs.md): Answers to common Bily implementation, event, identity, API, MCP, privacy, and production questions.

## OpenAPI Specs

- [openapi](https://docs.bily.ai/openapi.json)

## Optional

- [Bily](https://bily.ai)