# Depict Documentation - [Introduction](https://docs.depict.ai/headless/introduction.md): Depict for headless merchants: AI product discovery — collection merchandising, search and recommendations — served through an API and steered from one portal. - [Getting started](https://docs.depict.ai/headless/getting-started.md): From first login to a fully merchandised, measured storefront. - [Dashboard](https://docs.depict.ai/headless/features/dashboard.md): The portal landing page: headline KPIs, an issues queue, product and collection highlights, and traffic trends for the selected period. - [Collections](https://docs.depict.ai/headless/features/collections.md): Curate every collection with pinned and auto-sorted products, bulk actions, content cards and per-market settings. - [Collection analytics](https://docs.depict.ai/headless/features/collection-analytics.md): Per-collection performance: KPIs, conversion funnel, inventory risk, pinned-vs-auto health and benchmarking. - [Analytics](https://docs.depict.ai/headless/features/analytics.md): The merchant-wide analytics hub: per-area tabs, KPIs, conversion funnel, search insights, recommendation surface metrics, CSV export and analytics API keys. - [Products](https://docs.depict.ai/headless/features/products.md): Browse your catalog with performance metrics, manage stock-based visibility and edit product imagery. - [Search](https://docs.depict.ai/headless/features/search.md): Search analytics, synonyms, search content, the start view, and search configuration for the storefront search Depict serves. - [Boost & Bury](https://docs.depict.ai/headless/features/boost-and-bury.md): Storewide boost and bury rules: available conditions, market scoping and how rules interact. - [Recommendations](https://docs.depict.ai/headless/features/recommendations.md): Recommendation surfaces, the self-service rule editor, and the live preview of what each surface returns. - [Settings](https://docs.depict.ai/headless/features/settings.md): The Settings area: portal language, user management, attribute ingestion, storefront filters, appearance, market groups, tracking diagnostics and analytics API keys. - [Overview of Data Ingestion](https://docs.depict.ai/data-ingestion-guide/overview-of-data-ingestion.md): The three ways product data reaches Depict: Centra, Shopify, and the Push Product API. - [Centra](https://docs.depict.ai/data-ingestion-guide/centra-setup-guide.md): Connect a Centra store to Depict: the API token, the required permissions, and how sync works. - [Shopify](https://docs.depict.ai/data-ingestion-guide/shopify-setup-guide.md): Learn how to import your product data from Shopify. - [Introduction](https://docs.depict.ai/react-ui-guide/introduction.md): A guide for React/Next.js/Gatsby users to integrate with the Depict UI - [Data Ingestion](https://docs.depict.ai/react-ui-guide/data-ingestion.md): A reminder of the data ingestion process - [Compatibility and Browser Support for Depict Packages](https://docs.depict.ai/react-ui-guide/compatible-environments.md) - [Server-side rendering](https://docs.depict.ai/react-ui-guide/ssr.md): What @depict-ai/react-ui renders on the server, and what that means for Next.js and SEO - [Installation](https://docs.depict.ai/react-ui-guide/setup/installation.md) - [Configuring `DepictProvider`](https://docs.depict.ai/react-ui-guide/setup/depict-provider.md) - [Setting up routing](https://docs.depict.ai/react-ui-guide/setup/routing.md) - [Transforming and enriching display data](https://docs.depict.ai/react-ui-guide/setup/display-transformers.md) - [Import styling](https://docs.depict.ai/react-ui-guide/setup/styling.md): How to import the SDK styling into your project - [Setting up your product card](https://docs.depict.ai/react-ui-guide/setup/product-card.md): Your product card components needs to meet some specific requirements - [Overview](https://docs.depict.ai/react-ui-guide/search/overview.md): An overview of the search components and flow - [Adding a way to open the SearchModal](https://docs.depict.ai/react-ui-guide/search/modal.md) - [Configuring the DepictProvider for your search page](https://docs.depict.ai/react-ui-guide/search/configuring-provider.md) - [Adding the SearchPage to your site](https://docs.depict.ai/react-ui-guide/search/page.md) - [Overview](https://docs.depict.ai/react-ui-guide/listings/overview.md) - [Choosing a source of truth](https://docs.depict.ai/react-ui-guide/listings/id-source-of-truth.md): Who owns your listing pages? Let's find out! - [Adding the CategoryPage to your site](https://docs.depict.ai/react-ui-guide/listings/page.md) - [Rendering recommendations in a slider](https://docs.depict.ai/react-ui-guide/recommendations/slider.md) - [Rendering recommendations in a grid](https://docs.depict.ai/react-ui-guide/recommendations/grid.md) - [Introduction](https://docs.depict.ai/react-ui-guide/tracking/introduction.md): A guide to setting up tracking for Depict UI (React) integrations - [Product Card Tracking for Recommendations](https://docs.depict.ai/react-ui-guide/tracking/product-cards.md): For product cards that are NOT rendered *through* the Depict UI (SDK) - [Product Page Tracking](https://docs.depict.ai/react-ui-guide/tracking/product-pages.md): How to make sure DPC tracks your Product Details Page (PDP) views correctly. - [Add to cart tracking](https://docs.depict.ai/react-ui-guide/tracking/add-to-cart.md): You need to track both the add-to-cart button on your product page and, if applicable, on your product cards - [Purchase tracking](https://docs.depict.ai/react-ui-guide/tracking/purchases.md): To calculate revenue figures, you need to track purchases. This is done with the `purchase` event. - [Introduction](https://docs.depict.ai/js-ui-guide/introduction.md): A guide for integrating with the plain JavaScript flavour of the Depict UI - [Data Ingestion](https://docs.depict.ai/js-ui-guide/data-ingestion.md): A reminder of the data ingestion process - [Compatibility and Browser Support for Depict Packages](https://docs.depict.ai/js-ui-guide/compatible-environments.md) - [Installation](https://docs.depict.ai/js-ui-guide/setup/installation.md) - [Import styling](https://docs.depict.ai/js-ui-guide/setup/styling.md): How to import the SDK styling into your project - [Setting up JSX](https://docs.depict.ai/js-ui-guide/setup/setting-up-jsx.md): How to set up JSX in your build environment to create HTMLElements - [Setting up your product card](https://docs.depict.ai/js-ui-guide/setup/product-card.md): Your product card components needs to meet some specific requirements - [Overview](https://docs.depict.ai/js-ui-guide/search/overview.md): An overview of the search components and flow - [Creating a search page](https://docs.depict.ai/js-ui-guide/search/creating-page.md) - [Configuring the search provider](https://docs.depict.ai/js-ui-guide/search/provider.md) - [Transforming and enriching display data](https://docs.depict.ai/js-ui-guide/search/display-transformers.md) - [Adding a way to open the SearchModal](https://docs.depict.ai/js-ui-guide/search/modal.md) - [Adding the SearchPage to your site](https://docs.depict.ai/js-ui-guide/search/adding-page.md) - [Overview](https://docs.depict.ai/js-ui-guide/listings/overview.md) - [Choosing a source of truth](https://docs.depict.ai/js-ui-guide/listings/id-source-of-truth.md): Who owns your listing pages? Let's find out! - [Configuring the category provider](https://docs.depict.ai/js-ui-guide/listings/provider.md) - [Transforming and enriching display data](https://docs.depict.ai/js-ui-guide/listings/display-transformers.md) - [Adding the CategoryPage to your site](https://docs.depict.ai/js-ui-guide/listings/page.md) - [Rendering recommendations in a slider](https://docs.depict.ai/js-ui-guide/recommendations/slider.md) - [Rendering recommendations in a grid](https://docs.depict.ai/js-ui-guide/recommendations/grid.md) - [Introduction](https://docs.depict.ai/js-ui-guide/tracking/introduction.md): A guide to setting up tracking for Depict UI (JavaScript) integrations - [Set up DPC](https://docs.depict.ai/js-ui-guide/tracking/setup.md): Import and initialise the Depict Performance Client that ships inside @depict-ai/js-ui. - [Product Card Tracking](https://docs.depict.ai/js-ui-guide/tracking/product-cards.md): How to make sure DPC tracks your product cards correctly - [Product Page Tracking](https://docs.depict.ai/js-ui-guide/tracking/product-pages.md): How to make sure DPC tracks your Product Details Page (PDP) views correctly. - [Add to cart tracking](https://docs.depict.ai/js-ui-guide/tracking/add-to-cart.md): You need to track both the add-to-cart button on your product page and, if applicable, on your product cards - [Purchase tracking](https://docs.depict.ai/js-ui-guide/tracking/purchases.md): To calculate revenue figures, you need to track purchases. This is done with the `purchase` event. - [Integrating with the Platform API](https://docs.depict.ai/api-guide/introduction.md): What the Depict Platform API covers (search, listings, recommendations, tracking), the v2 vs v3 version status, and how markets, locales and currency are resolved. - [Data Ingestion](https://docs.depict.ai/api-guide/data-ingestion.md): A reminder of the data ingestion process - [Search](https://docs.depict.ai/api-guide/search.md): How to call the Platform API search endpoints: the /v3/search/results request and response, pagination, filter and sort semantics, and /v3/search/suggestions. - [Listings](https://docs.depict.ai/api-guide/listings.md): How to call the Platform API listing endpoints: addressing by listing_id or external_id, listing metadata and content cards, the navigation tree, and fetching products. - [Introduction](https://docs.depict.ai/api-guide/recommendations/introduction.md) - [JavaScript API client](https://docs.depict.ai/api-guide/recommendations/api-client.md): Install the Depict UI package, import the recommendations client, and fetch recommendations for a page, a product or a set of products. - [Interfacing directly with the API](https://docs.depict.ai/api-guide/recommendations/api.md): How to call POST /v3/recommend/products: request fields, how product_ids selects the recommendation flavor, the response shape on the wire, and the status of category recommendations. - [Introduction](https://docs.depict.ai/api-guide/tracking/introduction.md): A guide to setting up tracking for your Depict API integration - [Set up DPC](https://docs.depict.ai/api-guide/tracking/setup.md): Install, import and initialise the Depict Performance Client once, then send events from anywhere in your app. - [Which ID goes where](https://docs.depict.ai/api-guide/tracking/ids.md): Tracking uses three different kinds of ids. Sending the right one in each event is what makes attribution work. - [Product Card Tracking](https://docs.depict.ai/api-guide/tracking/product-cards.md): How to make sure DPC tracks your product cards correctly - [Product Page Tracking](https://docs.depict.ai/api-guide/tracking/product-pages.md): How to make sure DPC tracks your Product Details Page (PDP) views correctly. - [Add to cart tracking](https://docs.depict.ai/api-guide/tracking/add-to-cart.md): You need to track both the add-to-cart button on your product page and, if applicable, on your product cards - [Purchase tracking](https://docs.depict.ai/api-guide/tracking/purchases.md): To calculate revenue figures, you need to track purchases. This is done with the `purchase` event. - [Introduction](https://docs.depict.ai/other-guides/introduction.md): A collection of guides to provide examples of more framework specific integrations with Depict.ai - [Introduction](https://docs.depict.ai/other-guides/dynamic-collections/introduction.md) - [Storyblok + NextJS](https://docs.depict.ai/other-guides/dynamic-collections/storyblok-nextjs.md) - [A guide to setting up content blocks (React UI)](https://docs.depict.ai/other-guides/content-blocks-react.md) - [A guide to setting up content blocks (JS UI)](https://docs.depict.ai/other-guides/content-blocks-js-ui.md) - [Switching to the classic search modal (JS-UI)](https://docs.depict.ai/other-guides/switching-to-classic-modal-js-ui.md) - [Switching ot the classic search modal (React-UI)](https://docs.depict.ai/other-guides/switching-to-classic-modal-react.md) - [Depict UI migration v2 -> v3](https://docs.depict.ai/other-guides/sdk-migration-v2-v3.md) - [Depict UI migration v3 -> v4](https://docs.depict.ai/other-guides/sdk-migration-v3-v4.md) - [Naming discrepancies](https://docs.depict.ai/reference/glossary/naming-discrepancies.md) - [Types of product listing pages](https://docs.depict.ai/reference/glossary/types-of-listing-pages.md) - [Security Policy](https://docs.depict.ai/reference/security.md): Vulnerability reporting, remediation timelines, and security contact information for Depict. - [JavaScript UI Reference](https://docs.depict.ai/reference/search-sdk/js-ui.md) - [React UI Reference](https://docs.depict.ai/reference/search-sdk/search-react-sdk.md): Learn more about the Depict Search UI React SDK, its components and configuration. - [React UI Reference](https://docs.depict.ai/reference/listing-sdk/listing-page-react-sdk.md): Learn more about our React SDK, its components and configuration. - [JavaScript UI Reference](https://docs.depict.ai/reference/listing-sdk/js-ui.md) - [JavaScript UI Reference](https://docs.depict.ai/reference/listings-search/js-ui.md) - [Customize PLP Styling with SCSS](https://docs.depict.ai/reference/listings-search/customize-plp-styling-with-scss.md) - [Transforming and enriching display data](https://docs.depict.ai/reference/listings-search/display-transformers.md): How to use DisplayTransformers - [API client](https://docs.depict.ai/reference/recommendations-sdk/recommendations-sdk-api-wrapper.md): Fetching recommendations with our API wrapper - [Javascript UI Reference](https://docs.depict.ai/reference/recommendations-sdk/recommendations-sdk-js.md): Reference of the depict Recommendations vanilla JS SDK. - [React UI Reference](https://docs.depict.ai/reference/recommendations-sdk/recommendations-sdk-react.md): Reference of the depict Recommendations React components - [Introduction to Depict Performance Client](https://docs.depict.ai/reference/performance-client/introduction-to-depict-performance-client.md): Use our Depict Performance Client SDKs to track and monitor user behavior on your store. - [Getting started with Depict Performance Client](https://docs.depict.ai/reference/performance-client/performance-client.md): DPC handles performance tracking to enable the Depict AI to optimize recommendations and product listings. - [Example usage with Next.js](https://docs.depict.ai/reference/performance-client/example-usage-with-nextjs.md): Using DPC as a client-side library - [API Overview](https://docs.depict.ai/api-reference/headless/overview.md): The APIs behind Depict for headless merchants: the Portal API used by the merchant portal, and the Platform API that serves search, listings and recommendations to your shop. - [List Merchants Endpoint](https://docs.depict.ai/api-reference/merchants/list-merchants-endpoint.md) - [Get Merchant Endpoint](https://docs.depict.ai/api-reference/merchants/get-merchant-endpoint.md) - [Update Product Media Urls Endpoint](https://docs.depict.ai/api-reference/product-images/update-product-media-urls-endpoint.md) - [Update Collection Product Images Endpoint](https://docs.depict.ai/api-reference/product-images/update-collection-product-images-endpoint.md) - [Get Product Basic Metrics Endpoint](https://docs.depict.ai/api-reference/product-metrics/get-product-basic-metrics-endpoint.md) - [Get Product Overview Chart Endpoint](https://docs.depict.ai/api-reference/product-metrics/get-product-overview-chart-endpoint.md) - [Get Product Weekly Stats Endpoint](https://docs.depict.ai/api-reference/product-metrics/get-product-weekly-stats-endpoint.md) - [Get Product Toplist Endpoint](https://docs.depict.ai/api-reference/product-metrics/get-product-toplist-endpoint.md) - [List Products Post Endpoint](https://docs.depict.ai/api-reference/products/list-products-post-endpoint.md) - [Get Products Metrics Endpoint](https://docs.depict.ai/api-reference/products/get-products-metrics-endpoint.md): Per-product metrics for an explicit set of products. - [Get Dead Stock Products Endpoint](https://docs.depict.ai/api-reference/products/get-dead-stock-products-endpoint.md): Merchant-wide dead stock: products with stock on hand but zero sales in the metrics period. Scope matches the merchant overview's ``dead_stock`` tile (Tinybird-scoped); per-collection ``CollectionMetricsSummary.dead_stock`` additionally counts stocked products Tinybird hasn't seen. When the inventor… - [List Product Filters Endpoint](https://docs.depict.ai/api-reference/products/list-product-filters-endpoint.md) - [Get Product Visibility Endpoint](https://docs.depict.ai/api-reference/products/get-product-visibility-endpoint.md) - [Patch Product Visibility Endpoint](https://docs.depict.ai/api-reference/products/patch-product-visibility-endpoint.md) - [Get Product Endpoint](https://docs.depict.ai/api-reference/products/get-product-endpoint.md) - [Get Analytics Overview Endpoint](https://docs.depict.ai/api-reference/analytics/get-analytics-overview-endpoint.md): Merchant-wide analytics for the hub page. Defaults to last 30 days vs the previous 30; pass ``start_timestamp`` / ``end_timestamp`` (Unix seconds, UTC date only) for a custom range. ``None`` when the metrics backend is unavailable (degrade like api_v0's KPI endpoints, never a 500). - [Get Analytics Periods Endpoint](https://docs.depict.ai/api-reference/analytics/get-analytics-periods-endpoint.md) - [Compare Analytics Endpoint](https://docs.depict.ai/api-reference/analytics/compare-analytics-endpoint.md) - [Export Analytics Endpoint](https://docs.depict.ai/api-reference/analytics/export-analytics-endpoint.md) - [List Api Keys Endpoint](https://docs.depict.ai/api-reference/analytics/list-api-keys-endpoint.md) - [Create Api Key Endpoint](https://docs.depict.ai/api-reference/analytics/create-api-key-endpoint.md) - [Revoke Api Key Endpoint](https://docs.depict.ai/api-reference/analytics/revoke-api-key-endpoint.md) - [List Collections Endpoint](https://docs.depict.ai/api-reference/collections/list-collections-endpoint.md) - [Create Collection Endpoint](https://docs.depict.ai/api-reference/collections/create-collection-endpoint.md) - [List Collection Favourites Endpoint](https://docs.depict.ai/api-reference/collections/list-collection-favourites-endpoint.md) - [Add Collection Favourite Endpoint](https://docs.depict.ai/api-reference/collections/add-collection-favourite-endpoint.md) - [Remove Collection Favourite Endpoint](https://docs.depict.ai/api-reference/collections/remove-collection-favourite-endpoint.md) - [Get Collection Endpoint](https://docs.depict.ai/api-reference/collections/get-collection-endpoint.md) - [Delete Collection Endpoint](https://docs.depict.ai/api-reference/collections/delete-collection-endpoint.md) - [Save Collection Endpoint](https://docs.depict.ai/api-reference/collections/save-collection-endpoint.md) - [Get Collection Curation Endpoint](https://docs.depict.ai/api-reference/collections/get-collection-curation-endpoint.md) - [Discard Collection Curation Override Endpoint](https://docs.depict.ai/api-reference/collections/discard-collection-curation-override-endpoint.md) - [Get Collections Metrics Endpoint](https://docs.depict.ai/api-reference/collections/get-collections-metrics-endpoint.md): Metrics for an explicit set of collections in one request. - [Get Collections Metrics Summary Endpoint](https://docs.depict.ai/api-reference/collections/get-collections-metrics-summary-endpoint.md): Storewide totals over the whole catalog's metrics — the collections KPI row's source. Route safety is by shape, not declaration order: ``{collection_id}`` can't match across ``/`` so it can't swallow ``metrics/summary``, and ``/{collection_id}/metrics`` needs a literal ``metrics`` second segment — d… - [Get Collection Metrics Endpoint](https://docs.depict.ai/api-reference/collections/get-collection-metrics-endpoint.md) - [Get Collection Analytics Endpoint](https://docs.depict.ai/api-reference/collections/get-collection-analytics-endpoint.md) - [Compare Collection Analytics Endpoint](https://docs.depict.ai/api-reference/collections/compare-collection-analytics-endpoint.md) - [List Collection Products Endpoint](https://docs.depict.ai/api-reference/collections/list-collection-products-endpoint.md) - [Update Collection Parent Endpoint](https://docs.depict.ai/api-reference/collections/update-collection-parent-endpoint.md) - [Get Search Query Stats Endpoint](https://docs.depict.ai/api-reference/search-metrics/get-search-query-stats-endpoint.md) - [Get Auto Hide Settings Endpoint](https://docs.depict.ai/api-reference/settings/get-auto-hide-settings-endpoint.md) - [Update Auto Hide Settings Endpoint](https://docs.depict.ai/api-reference/settings/update-auto-hide-settings-endpoint.md) - [Update Auto Hide Exclude Products Endpoint](https://docs.depict.ai/api-reference/settings/update-auto-hide-exclude-products-endpoint.md) - [Get Listings](https://docs.depict.ai/api-reference/listing-v3/get-listings.md) - [Get Listing Via External Id](https://docs.depict.ai/api-reference/listing-v3/get-listing-via-external-id.md) - [Get Listing](https://docs.depict.ai/api-reference/listing-v3/get-listing.md) - [Create Events](https://docs.depict.ai/api-reference/events/create-events.md) - [Create Events V2](https://docs.depict.ai/api-reference/events/create-events-v2.md) - [Get Results](https://docs.depict.ai/api-reference/search/get-results.md) - [Get Suggestions](https://docs.depict.ai/api-reference/search/get-suggestions.md) - [Get Related Recommendations](https://docs.depict.ai/api-reference/search/get-related-recommendations.md) - [Search Through Text Content](https://docs.depict.ai/api-reference/search/search-through-text-content.md) - [Get Results](https://docs.depict.ai/api-reference/search/get-results-1.md) - [Get Suggestions](https://docs.depict.ai/api-reference/search/get-suggestions-1.md) - [Get Related Recommendations](https://docs.depict.ai/api-reference/search/get-related-recommendations-1.md) - [Recommend For User](https://docs.depict.ai/api-reference/recommendations/recommend-for-user.md) - [Recommend For Product And User](https://docs.depict.ai/api-reference/recommendations/recommend-for-product-and-user.md) - [Recommend For Category And User](https://docs.depict.ai/api-reference/recommendations/recommend-for-category-and-user.md) - [Recommend For Products And User](https://docs.depict.ai/api-reference/recommendations/recommend-for-products-and-user.md) - [Recommendations](https://docs.depict.ai/api-reference/recommendations/recommendations.md) - [Get Displays Endpoint V3](https://docs.depict.ai/api-reference/recommendations/get-displays-endpoint-v3.md) - [Get Markets](https://docs.depict.ai/api-reference/markets/get-markets.md) - [Get Locales](https://docs.depict.ai/api-reference/markets/get-locales.md) - [Product Listing Endpoint V2](https://docs.depict.ai/api-reference/product-listing/product-listing-endpoint-v2.md) - [Get Products In Listing, Via External Id](https://docs.depict.ai/api-reference/product-listing/get-products-in-listing-via-external-id.md) - [Get Products In Listing](https://docs.depict.ai/api-reference/product-listing/get-products-in-listing.md) - [Changelog](https://docs.depict.ai/changelog/headless.md): New features and improvements in the Depict platform for headless merchants and the Shopify theme app. - [Introduction](https://docs.depict.ai/shopify-lite/introduction.md): Depict: Search & Merchandising merchandises your existing Shopify collections — no theme rebuild, no code. - [Onboarding](https://docs.depict.ai/shopify-lite/onboarding.md): Installing Depict: Search & Merchandising — what happens on install, how the automatic theme setup works, the setup statuses, and password-protected storefronts. - [Theme setup: app embeds and blocks](https://docs.depict.ai/shopify-lite/theme-setup.md): What Depict adds to your theme through its theme app extension, how to switch each part on, and links that open the theme editor with the part already in place. - [Collections](https://docs.depict.ai/shopify-lite/collections.md): Activating collections, sort orders and pinning, versions and publishing, content cards, image settings, product duplicates, and collection analytics. - [Boost & Bury](https://docs.depict.ai/shopify-lite/boost-and-bury.md): Boost & Bury rules: rule types, the badges and their thresholds, rule ordering, defaults, and multi-store behavior. - [Recommendations](https://docs.depict.ai/shopify-lite/recommendations.md): Add a Depict recommendation carousel to your theme, for example "You may also like" on product pages. - [Styling recommendations with custom CSS](https://docs.depict.ai/shopify-lite/recommendations-custom-css.md): Restyle the Depict Recommendations section with custom CSS: its classes, data attributes and CSS variables, where to put your CSS, and copy-paste examples. - [Products](https://docs.depict.ai/shopify-lite/product-analytics.md): The Products page: per-product analytics — revenue and rank, the shopper funnel, daily trends, per-collection performance, inventory, and CSV export. - [Weekly Reports](https://docs.depict.ai/shopify-lite/weekly-reports.md): The Weekly Reports page: top products by clicks, add-to-carts and orders, the needs-attention lists, and CSV export. - [A/B testing](https://docs.depict.ai/shopify-lite/ab-testing.md): How A/B tests work: what varies between groups, how traffic is split, and how to read the results. - [Multi-store](https://docs.depict.ai/shopify-lite/multi-store.md): Connecting Shopify stores into a group, mapping collections, and what replicates between stores. - [Settings](https://docs.depict.ai/shopify-lite/settings.md): The Settings page and your plan: products, sizes and limits, product badge thresholds, the collection grid, market groups, catalog sync, integrations, and AI assistants. - [AI assistants](https://docs.depict.ai/shopify-lite/ai-assistants.md): Connecting Claude, ChatGPT or Codex to your store through Depict's MCP server: the endpoint URL, the approval screen, what an assistant can do, and revoking. - [Troubleshooting](https://docs.depict.ai/shopify-lite/troubleshooting.md): Common problems with Depict: Search & Merchandising collections and recommendations, and how to fix them. - [Introduction](https://docs.depict.ai/shopify-search/introduction.md): Integrate Depict search, listings and recommendations through the Depict Shopify apps - [Compatibility and Browser Support of the Depict Shopify App](https://docs.depict.ai/shopify-search/compatible-environments.md) - [Installing the app](https://docs.depict.ai/shopify-search/setup/installation.md) - [Adding a way to open the Search Modal](https://docs.depict.ai/shopify-search/blocks/search-modal.md) - [Search button settings](https://docs.depict.ai/shopify-search/blocks/search-button-settings.md): Customize the on-page button that opens the Depict search modal. - [Search customization overview](https://docs.depict.ai/shopify-search/blocks/search-customization-overview.md): Where to find Search by Depict customization settings in Shopify, and how they are organized. - [Layout & behaviour](https://docs.depict.ai/shopify-search/blocks/search-modal-layout.md): Global layout and behaviour settings for the Depict search modal (app embed: Depict Search layout). - [Theming](https://docs.depict.ai/shopify-search/blocks/search-modal-theming.md): Global visual styling for the Depict search modal (app embed: Depict Search theme). - [API Overview](https://docs.depict.ai/shopify-search/storefront-api.md): The storefront search API used by Search by Depict to serve search results. - [API Overview](https://docs.depict.ai/api-reference/lite/overview.md): The Search & Merchandising API: the REST API behind the Depict: Search & Merchandising Shopify app. - [Install or reinstall the app for the calling Shopify store](https://docs.depict.ai/api-reference/install-or-reinstall-the-app-for-the-calling-shopify-store.md): Creates the merchant for the Shopify store in the caller's session token, or marks an existing one reinstalled, then exchanges and stores a fresh offline Admin API token. Call it from the app's install flow only: it writes config.merchant, the default market, default boost/bury rules and the Shopify… - [Whether the store's stored Shopify token still works](https://docs.depict.ai/api-reference/whether-the-stores-stored-shopify-token-still-works.md): Probes the stored offline Admin API token of the store in the caller's session token. Returns `needs_reinstall: true` when the store is unknown, has no usable config, or Shopify answers 401 for the token (then marks the app uninstalled); the app then re-runs the install flow. Any other Shopify answe… - [The merchants the caller may act for](https://docs.depict.ai/api-reference/the-merchants-the-caller-may-act-for.md): Returns the merchant records the caller can use: every installed merchant for staff, or just the caller's own store for a merchant token. Call it first to discover merchant ids and each store's settings. Read-only. - [One merchant record](https://docs.depict.ai/api-reference/one-merchant-record.md): Returns one merchant's record: shop domain, currency, grid columns, onboarding and multi-store state. Read-only. - [How far the merchant's first catalog import has come](https://docs.depict.ai/api-reference/how-far-the-merchants-first-catalog-import-has-come.md): Returns whether the first full Shopify catalog import has finished, its percentage, and the last sync time. Poll it after install until `has_run_at_least_one_ingestion` is true; for the index side use catalog-readiness. Read-only. - [The merchant's Shopify markets and their countries](https://docs.depict.ai/api-reference/the-merchants-shopify-markets-and-their-countries.md): Returns every Shopify market of a multi-market store with its countries and whether Depict serves it. A single-market store returns []. Read-only. - [The countries mapped to one market](https://docs.depict.ai/api-reference/the-countries-mapped-to-one-market.md): Returns the ISO country codes mapped to one market, sorted. Read-only. - [Whether the storefront is behind Shopify's password page](https://docs.depict.ai/api-reference/whether-the-storefront-is-behind-shopifys-password-page.md): Returns a bare boolean: true when the online store is password-protected, so shopper-facing previews cannot load. Asks Shopify live; a 502 means Shopify could not be asked (dead token, frozen shop, no config), so the answer is unknown, not false. Read-only. - [Set the option name the collection grid groups variants by](https://docs.depict.ai/api-reference/set-the-option-name-the-collection-grid-groups-variants-by.md): Sets which product option (e.g. Color) groups variants into one card in the collection grid; omit the parameter to clear it. Writes config.merchant.variant_group_by_name; returns null. - [Compose a recommendation surface](https://docs.depict.ai/api-reference/compose-a-recommendation-surface.md): Composes a surface by id (or an unsaved `draft` of it) from the merchant's current candidate pools, as the storefront would, and returns the product id per slot with the shuffle seed used. Pass `anchor` for a product or category surface and `recent_views` to exercise history-seeded steps. Use it to… - [List the merchant's recommendation surfaces](https://docs.depict.ai/api-reference/list-the-merchants-recommendation-surfaces.md): Returns every recommendation surface the merchant has configured, as an object keyed by surface name in creation order. Call it to discover which surfaces exist (and their ids) before reading, editing, previewing or pinning one. Read-only; a merchant with recommendations not set up gets `{}`. - [The recommender catalog a surface step can use](https://docs.depict.ai/api-reference/the-recommender-catalog-a-surface-step-can-use.md): Returns the recommender catalog: every step `kind` a surface may use, its display name, and whether it needs a product anchor (`bucket: per_product`). Call it before building or editing a surface's `steps`. Static and read-only. - [Read one recommendation surface](https://docs.depict.ai/api-reference/read-one-recommendation-surface.md): Returns one saved surface by name: its id, context, steps, filters, limit, exclusions and the read-only serving directives. Call it to inspect a surface before changing it with the PUT on the same path. Read-only. - [Create or replace a recommendation surface](https://docs.depict.ai/api-reference/create-or-replace-a-recommendation-surface.md): Creates the surface named in the path, or replaces its editable fields (context, steps, filters, limit, exclusions) if it exists; an existing surface keeps its id and serving directives. The body's `name` must equal the path's. Side effects: writes the storefront metaobject in Shopify, then the reco… - [Delete a recommendation surface and its pins](https://docs.depict.ai/api-reference/delete-a-recommendation-surface-and-its-pins.md): Deletes the surface named in the path. Side effects: deletes its Shopify metaobject, removes it from the recommendations config, deletes all its pins, and replicates the deletion to linked stores; other surfaces are unaffected and no recompute is queued. Returns `{deleted: }`. Irreversible. - [Read a surface's pin sets](https://docs.depict.ai/api-reference/read-a-surfaces-pin-sets.md): Returns every pin set of a surface: one entry per (anchor_type, anchor_id, market_id), each listing the pinned products by slot position. Call it before saving pins, since a save replaces a whole set. Read-only. - [Save one pin set of a surface](https://docs.depict.ai/api-reference/save-one-pin-set-of-a-surface.md): Saves one pin set of a surface: the body is the complete set for one (anchor_type, anchor_id, market_id), and the stored pins for that set are reconciled to it (added, moved, removed); an empty `pins` clears the set. Other sets are untouched. Side effect: queues a background recompute of the surface… - [Whether the merchant's recommendations are computed yet](https://docs.depict.ai/api-reference/whether-the-merchants-recommendations-are-computed-yet.md): Reports whether the merchant's recommendations have been computed: the run in flight (if any), the last finished run, and `ready` (the last run completed with at least one market). Poll it after enabling recommendations or changing surfaces to know when storefront recommendations are live. Read-only… - [Preview a saved surface](https://docs.depict.ai/api-reference/preview-a-saved-surface.md): Composes a saved surface right now from the current candidate pools, exactly as the storefront would for the given anchor and market, and returns the product ids per slot (pins included). A `product` or `category` surface needs `anchor_id`; an `any` surface must omit it. Read-only: nothing is writte… - [Preview an unsaved draft of a surface](https://docs.depict.ai/api-reference/preview-an-unsaved-draft-of-a-surface.md): As the GET preview, but composes the unsaved `surface` in the body (the upsert's shape) in place of the saved one, keyed to the saved surface's id and directives. Use it to show the effect of edits before saving. Read-only: nothing is written. - [Recommendation performance totals for a window](https://docs.depict.ai/api-reference/recommendation-performance-totals-for-a-window.md): Returns the merchant's recommendation performance over [from_date, to_date]: impressions, clicks, CTR, attributed add-to-carts, orders and revenue, and the derived rates, plus when the merchant's recommendation data starts. Call it for headline numbers or to compare two windows (call twice). Counts… - [Recommendation performance per day](https://docs.depict.ai/api-reference/recommendation-performance-per-day.md): Returns the same figures as the totals route, one point per day of [from_date, to_date], optionally narrowed to one surface. Call it for trends and sparklines. Counts come from storefront events attributed to recommendation carousels; money figures use the shared Depict attribution rule. Read-only;… - [One recommendation surface's performance totals](https://docs.depict.ai/api-reference/one-recommendation-surfaces-performance-totals.md): As the totals route, narrowed to one surface by id, with the surface's current name. An unknown or deleted surface answers 200 with its history (zeros if none) and a null name, never 404. Counts come from storefront events attributed to recommendation carousels; money figures use the shared Depict a… - [The merchant's plan, usage and entitlements](https://docs.depict.ai/api-reference/the-merchants-plan-usage-and-entitlements.md): Everything the portal gates on: active collections vs the cap, this month's sessions (and a projection) vs the quota, trial state, whether the store is frozen or erroring, the active Shopify subscription, and the plan-derived entitlements. Read-only; computed fresh on every call. - [The plans the merchant can buy](https://docs.depict.ai/api-reference/the-plans-the-merchant-can-buy.md): Every sellable catalogue plan (products + size) with its monthly and annual price, trial days and session quota, in catalogue order. Read-only. Subscribe to one with POST /settings/subscription using the same products and size. - [Start a legacy basic subscription](https://docs.depict.ai/api-reference/start-a-legacy-basic-subscription.md): Creates a pending Shopify app subscription on the legacy basic plan and returns the confirmation URL the merchant must open to approve it; nothing is billed until they do. Side effect: a pending AppSubscription in Shopify. New subscriptions should use POST /settings/subscription (products + size). - [Start a legacy essentials subscription](https://docs.depict.ai/api-reference/start-a-legacy-essentials-subscription.md): Creates a pending Shopify app subscription on the legacy essentials plan and returns the confirmation URL the merchant must open to approve it; nothing is billed until they do. Side effect: a pending AppSubscription in Shopify. New subscriptions should use POST /settings/subscription (products + siz… - [Start a legacy pro subscription](https://docs.depict.ai/api-reference/start-a-legacy-pro-subscription.md): Creates a pending Shopify app subscription on the legacy pro plan and returns the confirmation URL the merchant must open to approve it; nothing is billed until they do. Side effect: a pending AppSubscription in Shopify. New subscriptions should use POST /settings/subscription (products + size). - [Subscribe to, upgrade or downgrade to a plan (products + size)](https://docs.depict.ai/api-reference/subscribe-to-upgrade-or-downgrade-to-a-plan-products-+-size.md): Resolves the selection to a catalogue plan and creates a pending Shopify app subscription replacing the current one; returns the confirmation URL the merchant must open to approve it. Nothing is billed or changed until they approve, except that a downgrade to a plan without Merchandising deactivates… - [Cancel the subscription and drop to the free tier](https://docs.depict.ai/api-reference/cancel-the-subscription-and-drop-to-the-free-tier.md): Downgrades the merchant to the free tier. Side effects, in order: sync-back to Shopify is switched off for the listed collections (at most 3; more is a 400 before anything changes), then the Shopify app subscription is cancelled with proration. Answers null. - [The thresholds behind the computed product badges](https://docs.depict.ai/api-reference/the-thresholds-behind-the-computed-product-badges.md): How the dynamic badges are computed for this merchant: the New in window, how many products count as bestsellers, slow movers and trending, the low-stock percentage and the order window. Read-only; a merchant that never saved settings gets the defaults. - [Save the thresholds behind the computed product badges](https://docs.depict.ai/api-reference/save-the-thresholds-behind-the-computed-product-badges.md): Replaces the merchant's badge thresholds (all six counts are required; `new_in_date_source` defaults to published_at). Side effects: a new settings version is stored with the caller as author, and every collection that syncs back to Shopify is re-ordered there with the new badges (best effort: a fai… - [Record that the Shopify app install finished](https://docs.depict.ai/api-reference/record-that-the-shopify-app-install-finished.md): Sends the `shopify_app_installed` analytics event for the merchant (with its domain and store name, attributed to the calling user). Side effect: one PostHog event; staff users are never tracked. Call it once when onboarding completes. Answers null. - [Where a merchant's catalog is between Shopify and the search index](https://docs.depict.ai/api-reference/where-a-merchants-catalog-is-between-shopify-and-the-search-index.md): Returns where the merchant's catalog is between Shopify and the search/recommendations index: the pipeline `stage`, whether search is `serving`, and document counts. Call it to tell whether search and recommendations can work yet, or how far an import has come; the portal polls it every few seconds… - [The install screen's welcome carousel](https://docs.depict.ai/api-reference/the-install-screens-welcome-carousel.md): Returns the slides the install screen shows while a new store's catalog imports, as the back office saved them. The same for every merchant; call it to see the current carousel. Read-only. - [The What's New entries the back office switched on](https://docs.depict.ai/api-reference/the-whats-new-entries-the-back-office-switched-on.md): Returns the product-news entries currently live for the app's What's New modal. The same for every merchant; each entry says which stores should see it (`installed_before`). Read-only. - [The Inspiration feed of published collections, one page at a time](https://docs.depict.ai/api-reference/the-inspiration-feed-of-published-collections-one-page-at-a-time.md): Returns one page of collections other Depict brands published in the last 30 days, for browsing ideas: filter by features used, text, or brands live with a product; sort by likes or recency. Also returns the total and chip counts. `merchant_id` scopes authorization only; the feed spans all brands. R… - [The store's Shopify name and brand logo](https://docs.depict.ai/api-reference/the-stores-shopify-name-and-brand-logo.md): Returns the store's name and Shopify brand logo (Settings > Brand), read live from the Shopify Storefront API. Call it to render the merchant's brand, e.g. in a search preview. Read-only. - [The merchant's portal feature flags](https://docs.depict.ai/api-reference/the-merchants-portal-feature-flags.md): Returns which portal features are switched on for the merchant (e.g. search_synonyms) and when onboarding was last reset. Call it before using a gated surface. Never fails for an authorized caller: missing config means every flag off. Read-only. - [List the merchant's boost/bury rules](https://docs.depict.ai/api-reference/list-the-merchants-boostbury-rules.md): Returns every boost/bury rule the merchant has, ordered by id. These rules are merchant-wide: the collection sorter applies them to every automatically sorted collection (per-collection rules live on the collection version instead). Read-only. Call it before PUT /boost-bury/rules, which replaces the… - [List the product tags a tag rule can match](https://docs.depict.ai/api-reference/list-the-product-tags-a-tag-rule-can-match.md): Returns every distinct Shopify product tag in the merchant's ingested catalog, sorted, for building `type: "tag"` rules. Read-only; reflects the last catalog sync, not live Shopify. - [Replace the merchant's boost/bury rules](https://docs.depict.ai/api-reference/replace-the-merchants-boostbury-rules.md): Replaces ALL of the merchant's boost/bury rules with `rules` in one atomic write; any rule not sent is deleted, and an empty list clears them. To add or edit one rule, GET /boost-bury first and send the full list back. Side effects: the new rules take effect the next time collections are sorted (no… - [Merchant-wide collection traffic totals for a window](https://docs.depict.ai/api-reference/merchant-wide-collection-traffic-totals-for-a-window.md): Returns merchant-wide collection-page traffic (views, clicks, shoppers, click-through) summed over all collections for [from_date, to_date], and for the same-length window immediately before it so a caller can show a delta. Read-only; answers from Tinybird analytics, cached privately for 5 minutes.… - [The metafield keys a merchant's catalog carries](https://docs.depict.ai/api-reference/the-metafield-keys-a-merchants-catalog-carries.md): Lists every Shopify product metafield key (with its type) found in the merchant's synced catalog, most common first, with how many products carry it and how many distinct values it takes. Call it to discover which metafields a collection can be sorted by or which a boost/bury rule or badge can match… - [The distinct values one metafield key takes](https://docs.depict.ai/api-reference/the-distinct-values-one-metafield-key-takes.md): Lists the distinct values one product metafield key takes across the merchant's synced catalog, most common first, with the number of products per value (capped, see `limitHit`). Call it after /product-metafield-keys to offer concrete values for a metafield rule or badge. Read-only; same full-catalo… - [Record one product-analytics event for a merchant](https://docs.depict.ai/api-reference/record-one-product-analytics-event-for-a-merchant.md): Sends one PostHog event (`type`, with `payload` as its properties) attributed to the caller and grouped under the merchant. Call it for in-app user actions worth counting; it is fire-and-forget, so nothing is read back. Side effect: one PostHog capture, sent after the response. Returns JSON `null`. - [Record that a Shopify staff member opened the app](https://docs.depict.ai/api-reference/record-that-a-shopify-staff-member-opened-the-app.md): Called once per app load from inside Shopify admin with the Shopify session token as the bearer. Answers JSON `null` straight after auth; behind the response it exchanges the token for an online grant, upserts the staff member's verified email (read back by `/users/me`), and sends `shopify_app_launc… - [The merchant's open onboarding messages and setup-guide copy](https://docs.depict.ai/api-reference/the-merchants-open-onboarding-messages-and-setup-guide-copy.md): Lists the in-app messages the onboarding programme queued for the merchant that are neither dismissed nor expired, plus the copy (headline, per-step text, hidden steps, order) of the Home, Search and Recommendations setup guides from the shared back-office template. Read-only and uncached; the porta… - [Mark an onboarding message seen, clicked or dismissed](https://docs.depict.ai/api-reference/mark-an-onboarding-message-seen-clicked-or-dismissed.md): Records one transition on a message from `onboardingMessages`. Each event is stored once (its first time); a repeat answers `recorded: false` and changes nothing. Side effect: a dismissed message stops being listed. - [List the Inspiration gallery of published collections](https://docs.depict.ai/api-reference/list-the-inspiration-gallery-of-published-collections.md): Returns up to 150 collections that merchants published to the shared Inspiration gallery in the last 30 days, across ALL merchants (the list does not depend on `merchant_id`, which only authorizes the caller). Read-only. Use it to browse examples. The trailing slash in the path is required. - [Set the like count of an Inspiration gallery entry](https://docs.depict.ai/api-reference/set-the-like-count-of-an-inspiration-gallery-entry.md): Sets `likes` on one gallery entry, which usually belongs to ANOTHER merchant: the body's merchant_id/collection_id name the entry (take them from GET /published-collections/), while the query's merchant_id is the caller. It sets the count, it does not increment it, so send the entry's current likes… - [Publish a collection to the Inspiration gallery](https://docs.depict.ai/api-reference/publish-a-collection-to-the-inspiration-gallery.md): Renders a PNG preview of the merchant's live collection page (with the given theme template) and adds or refreshes its entry in the shared Inspiration gallery, where every merchant can see it; re-publishing resets the entry's likes to 0. Then queues a Shopify order sync-back for the collection. If t… - [Upload an image or video file to the merchant's Shopify Files](https://docs.depict.ai/api-reference/upload-an-image-or-video-file-to-the-merchants-shopify-files.md): Streams one multipart `file` into Shopify Files (staged upload, fileCreate), waits until Shopify has processed it, and returns the file node, whose `id` a content block then references. Side effects: creates a Shopify file in this store, and in every multi-store sibling linked through `collection_id… - [Copy an image or video from a public URL into the merchant's Shopify Files](https://docs.depict.ai/api-reference/copy-an-image-or-video-from-a-public-url-into-the-merchants-shopify-files.md): Downloads `url` and uploads it to Shopify Files like /upload does (same waiting, same multi-store fan-out and side effects), returning the processed file node. Used to import Instagram media into a content block. A source that answers 4xx (e.g. an expired Instagram CDN link) is a 400; the source mus… - [Search or page through a merchant's products](https://docs.depict.ai/api-reference/search-or-page-through-a-merchants-products.md): Finds products whose title, any variant SKU, product id or any tag contains `query` (case-insensitive); an exact product-id match sorts first. A blank `query` pages the whole catalogue, or one collection with `collection_id` (in the collection's order unless `sort` is given), and also returns the sc… - [The badges a product currently earns](https://docs.depict.ai/api-reference/the-badges-a-product-currently-earns.md): Computed merchandising badges for one product (on sale, stock state, bestseller, trending, new in, tag/collection badges, ...), store-wide scope. Read-only. Returns [] when the product earns none, and also when the badge service cannot answer (badges are decoration, so a failure is logged, not surfa… - [A product's available stock per variant and market group](https://docs.depict.ai/api-reference/a-products-available-stock-per-variant-and-market-group.md): Available quantity of each variant in each of the merchant's market groups. Read-only. A single-market store, or a failed stock read, answers the empty payload (no groups). - [One product's sales and grid performance over a date range](https://docs.depict.ai/api-reference/one-products-sales-and-grid-performance-over-a-date-range.md): Revenue, units, conversion, grid views/clicks, add-to-carts and the product score for [from_date, to_date], each with the previous period's value; daily series; the collections the product sits in with its position and clicks; and its revenue rank. Read-only. At most 365 days. Amounts are in the sho… - [An AI assistant's pending connection request, for the consent panel](https://docs.depict.ai/api-reference/an-ai-assistants-pending-connection-request-for-the-consent-panel.md): Reads the request an MCP client (an AI assistant such as Claude Code) parked when it started signing in to a store's endpoint: which client asks, where approving sends the browser, for which scopes, on which store. The Settings page calls it with the link's `mcp_txn` to render the consent panel, the… - [Approve an AI assistant's connection request](https://docs.depict.ai/api-reference/approve-an-ai-assistants-connection-request.md): Approves a request read with GET /mcp/consent: grants the MCP client the scopes it asked for and the user approved, on the request's store, and answers the client's OAuth redirect. Navigate the top-level window to `redirect_to` to finish connecting. Side effects: one OAuth grant for the store, repla… - [Decline an AI assistant's connection request](https://docs.depict.ai/api-reference/decline-an-ai-assistants-connection-request.md): Declines a request read with GET /mcp/consent: nothing is granted. The client is told (`redirect_to` carries `error=access_denied`) only when its redirect URI is on this computer (loopback): anyone can register any other, and following it would turn a click on Cancel into a redirect to a stranger's… - [The AI assistants connected to a store](https://docs.depict.ai/api-reference/the-ai-assistants-connected-to-a-store.md): Lists the store's OAuth grants to MCP clients (AI assistants such as Claude Code), newest first: one per connected assistant, with its name, scopes and approval time. Never carries tokens. Read-only; the Settings page shows it under Connections, and a `grant_id` from it disconnects that assistant th… - [Disconnect an AI assistant from a store](https://docs.depict.ai/api-reference/disconnect-an-ai-assistant-from-a-store.md): Revokes one grant from GET /mcp/grants and every token issued under it: the assistant's next call is refused, and it has to be connected again. Idempotent: an unknown or already revoked grant also answers 204. - [The merchant's published Shopify theme and Depict's footprint in it](https://docs.depict.ai/api-reference/the-merchants-published-shopify-theme-and-depicts-footprint-in-it.md): Reads the store's themes from the Shopify Admin API, picks the published (`main`) one and reports whether Depict's inline script and a Depict collection template are installed in it. Call it to decide whether the theme setup steps are done. Read-only; two Shopify calls per request. - [How far the merchant's automatic theme onboarding got](https://docs.depict.ai/api-reference/how-far-the-merchants-automatic-theme-onboarding-got.md): One word for the whole store, reduced over every theme Depict tried to onboard: `success` beats `warning` beats `failure`; `pending` when nothing has run yet. Returns a bare JSON string. Read-only. - [Every theme-onboarding run for a merchant, newest first](https://docs.depict.ai/api-reference/every-theme-onboarding-run-for-a-merchant-newest-first.md): The full history behind the admin Theme Onboardings page: per run, the theme, when it ran, and each resource Depict generated (with the patched file and whether it changed against the next-older run). Unpaginated and potentially tens of MB for long-lived stores; bodies past 8 MB stream, so a late fa… - [Read the merchant's search relevance settings](https://docs.depict.ai/api-reference/read-the-merchants-search-relevance-settings.md): Returns how storefront search ranks and filters for the merchant: keyword/meaning blend, searchable fields with weights, filter facets, sold-out handling and synonym groups. Unset values come back resolved to the serving defaults. Read-only. A 404 means the merchant has no Search section yet; the po… - [Change search settings and the empty-state configuration](https://docs.depict.ai/api-reference/change-search-settings-and-the-empty-state-configuration.md): Partial update of the merchant's search config: every field is optional and an omitted field keeps its stored value; `search_configuration` merges key by key. Writes `config.gpt_search_config`, which live storefront search reads, so a save changes what shoppers see. Read back with the configuration… - [Read the search empty-state configuration](https://docs.depict.ai/api-reference/read-the-search-empty-state-configuration.md): What the search overlay shows before the shopper types: product sort, pinned products, suggestion chips per locale, blocked suggestion terms, generator instructions and UI string overrides. Read-only; change it with the search-config PATCH. The product preview itself is not here (runway's public /em… - [List products hidden from search](https://docs.depict.ai/api-reference/list-products-hidden-from-search.md): Products the merchant excluded from storefront search results, with the title and image captured when they were picked. Read-only. - [Replace the products hidden from search](https://docs.depict.ai/api-reference/replace-the-products-hidden-from-search.md): Whole-replaces the excluded-products list (send the full list; `[]` clears it). Duplicate ids are dropped, first wins. Live search stops returning these products. - [List product tags hidden from search](https://docs.depict.ai/api-reference/list-product-tags-hidden-from-search.md): Shopify product tags whose products never appear in storefront search. Read-only. - [Replace the product tags hidden from search](https://docs.depict.ai/api-reference/replace-the-product-tags-hidden-from-search.md): Whole-replaces the excluded-tags list (`[]` clears it); tags are trimmed and deduplicated. Live search stops returning products carrying any of them. - [Where the merchant's search onboarding stands](https://docs.depict.ai/api-reference/where-the-merchants-search-onboarding-stands.md): The state of adding Depict search to the merchant's storefront theme: a background job prepares a search header on an unpublished copy of the live theme, then builds that copy for the merchant to preview and publish. Poll it after searchOnboardingEnable or searchOnboardingGoLive. Read-only. - [Start preparing the search header on the merchant's theme](https://docs.depict.ai/api-reference/start-preparing-the-search-header-on-the-merchants-theme.md): Queues the background job that prepares Depict's search header for the merchant's live theme (nothing is published; the result is stashed). Call once; then poll searchOnboardingStatus until `stashed`, and continue with searchOnboardingGoLive. Needs a plan that includes Search. - [Build the unpublished theme copy with search in it](https://docs.depict.ai/api-reference/build-the-unpublished-theme-copy-with-search-in-it.md): Queues the job that duplicates the live theme and applies the prepared search header to the copy. Allowed once the status is `stashed` (or to retry `golive_failed`, or to recreate at `live_ready`). Poll searchOnboardingStatus until `live_ready`, which carries the editor and preview links; the mercha… - [Daily results of a collection A/B test](https://docs.depict.ai/api-reference/daily-results-of-a-collection-ab-test.md): Page views, clicks, add-to-carts and purchases per day for variant A (the original collection) and B (Depict's), their rates, and a p-value per rate over the whole window. Read the test's dates from its metaobject and pass them as from_date/to_date. Read-only; the input for abTestGenerateConclusion. - [Write the plain-language conclusion of an A/B test](https://docs.depict.ai/api-reference/write-the-plain-language-conclusion-of-an-ab-test.md): Asks the model to explain the test's result from its metrics (abTestMetrics) and stores the text on the test's Shopify metaobject. If `metaobject.generated_conclusion` is already non-empty it is returned unchanged: no model call, no write. Otherwise it costs a model call and writes to Shopify. - [Hourly search funnel: searches, clicks, carts, orders, revenue](https://docs.depict.ai/api-reference/hourly-search-funnel:-searches-clicks-carts-orders-revenue.md): The storefront search funnel per hour, plus exact per-window totals counted in searches. Revenue is attributed by the one Depict rule and converted to `currency`. Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read… - [Hourly conversion of sessions that searched](https://docs.depict.ai/api-reference/hourly-conversion-of-sessions-that-searched.md): Sessions with a search, and how many of those purchased, per hour. Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read-only. - [Hourly purchase rate of sessions that did not search](https://docs.depict.ai/api-reference/hourly-purchase-rate-of-sessions-that-did-not-search.md): The baseline to compare search conversion against. Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read-only. - [Daily search health: no-results, click rates, latency](https://docs.depict.ai/api-reference/daily-search-health:-no-results-click-rates-latency.md): Per day: searches, no-result rate, click-through, no-click rate, median click position and index latency. Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read-only. - [Search totals for the window](https://docs.depict.ai/api-reference/search-totals-for-the-window.md): One row per window: searches, users, clicks and the rates. Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read-only. - [Searches by where the shopper started them](https://docs.depict.ai/api-reference/searches-by-where-the-shopper-started-them.md): Searches, sessions and clicks per entry point (e.g. header search, search page). Takes the current and previous windows (from_ts/to_ts, prev_from_ts/prev_to_ts) and answers both, for period-over-period comparison. Read-only. - [Per-query table: what shoppers searched and how it went](https://docs.depict.ai/api-reference/per-query-table:-what-shoppers-searched-and-how-it-went.md): One row per search query in the current window, sorted by `order_by` and paged with offset/page_size: searches, no-results, clicks, no-click rate, median click position. Use it to find queries that return nothing or get no clicks. Read-only. - [Countries that searched in a date range](https://docs.depict.ai/api-reference/countries-that-searched-in-a-date-range.md): The country codes seen in the inclusive from_date..to_date range, for a country filter. Not narrowed by country. Read-only. - [Whether the store's catalog is indexed for search yet](https://docs.depict.ai/api-reference/whether-the-stores-catalog-is-indexed-for-search-yet.md): How far catalog indexing has come (0–100) with a display line, and when the shop's search data starts. Poll until has_run_at_least_one_ingestion. Read-only. - [Clicks, views and CTR per product in one collection](https://docs.depict.ai/api-reference/clicks-views-and-ctr-per-product-in-one-collection.md): Per product in the collection's grid over from_date..to_date: clicks, share of the top product's clicks, average grid position, views and CTR. Optionally narrowed to one market or market group. Read-only. - [Per-product funnel: clicks, carts, orders, performance score](https://docs.depict.ai/api-reference/per-product-funnel:-clicks-carts-orders-performance-score.md): A page of products ranked by `order_by` (the performance score by default), each with clicks, add-to-carts, orders, views, revenue and their previous-period values, the product itself, the collections it sits in and a Need attention verdict. Storewide, or one collection's products with `collection_i… - [Store-wide clicks, add-to-carts and orders for a window](https://docs.depict.ai/api-reference/store-wide-clicks-add-to-carts-and-orders-for-a-window.md): The Analytics funnel's totals for from_date..to_date and the period before it, with attributed revenue and distinct store orders. Read-only. - [Revenue and orders Depict drove, per feature](https://docs.depict.ai/api-reference/revenue-and-orders-depict-drove-per-feature.md): Under the one attribution rule (a purchased line belongs to the feature the shopper last clicked that product on within window_hours before buying): lines, orders, revenue and touches for collections, recommendations and search, plus unattributed, Depict total and the whole store, for the window and… - [Cart and order stages each Depict feature led to](https://docs.depict.ai/api-reference/cart-and-order-stages-each-depict-feature-led-to.md): The bridged funnel stages (carts, carted, ordered, orders) of the collection, recommendation and search funnels under the same rule as depictAttribution, for the window and the one before. Read-only. - [Storefront sessions per day](https://docs.depict.ai/api-reference/storefront-sessions-per-day.md): Daily storefront sessions over from_date..to_date for the dashboard's traffic trend. Read-only. - [List the stores in a merchant's multi-store group](https://docs.depict.ai/api-reference/list-the-stores-in-a-merchants-multi-store-group.md): Every store (merchant) in the same multi-store group as `merchant_id`, the merchant itself included. Call it to find the group's other stores before reading or changing cross-store collection links. Empty when the merchant is in no group. Read-only. - [A collection's copies across the multi-store group, with replication sources](https://docs.depict.ai/api-reference/a-collections-copies-across-the-multi-store-group-with-replication-sources.md): For one of `merchant_id`'s collections, every linked copy in the group's stores (the collection itself included) and which store each copy replicates from. Call it before editing replication for a collection. Empty when the merchant has no group or the collection is not linked. Read-only. - [The multi-store group's cross-store collection links](https://docs.depict.ai/api-reference/the-multi-store-groups-cross-store-collection-links.md): Every collection linked across two or more stores of the group, plus every live collection of every store (to label them). The caller must belong to the group (a superuser may read any). Read-only. - [Connect or release collections across the group's stores](https://docs.depict.ai/api-reference/connect-or-release-collections-across-the-groups-stores.md): Puts `connect.collections` into one cross-store connection (an existing `group_collection_id`, or a new one) and/or releases `disconnect.collections` from theirs (the mapping row stays, unlinked). Every merchant named must belong to the group. Side effects: writes mapping rows; if the group has auto… - [Connect another store to this merchant's multi-store group](https://docs.depict.ai/api-reference/connect-another-store-to-this-merchants-multi-store-group.md): Joins `merchant_id` and the store whose activation code is given into one multi-store group (creating the group if neither has one). Call it when a merchant enters another store's activation code. Side effect: writes both merchants' group. Follow with create-collection-mappings to link their collect… - [Remove a store from its multi-store group](https://docs.depict.ai/api-reference/remove-a-store-from-its-multi-store-group.md): Clears `merchant_id`'s multi-store group. Refused while the store still has collection mappings in the group or other stores replicate from it; unlink those first (POST unlink-collections). Side effect: writes the merchant's group. A no-op for a merchant in no group. - [Read the multi-store group's settings](https://docs.depict.ai/api-reference/read-the-multi-store-groups-settings.md): The replication and publish-sync toggles of `merchant_id`'s group. A group that never changed a toggle answers the defaults (auto-replicate off, publish-sync on, recommendations off), and those are the values in effect, not a guess: fan-out and replication read the same defaults. A merchant in no gr… - [Change the multi-store group's settings](https://docs.depict.ai/api-reference/change-the-multi-store-groups-settings.md): Sets the toggles present in the body for `merchant_id`'s whole group and returns the resulting settings. Side effects: enabling auto_replicate_enabled makes the caller the replication source (if none is recorded) and stamps existing links to replicate from it; enabling sync_publish_status publishes… - [This store's replica collections that are unpublished while their source is live](https://docs.depict.ai/api-reference/this-stores-replica-collections-that-are-unpublished-while-their-source-is-live.md): Collections of `merchant_id` that replicate a live collection of another store in the group but are themselves unpublished. An empty list also answers a merchant in no group and a group with publish-sync off, where drift is expected rather than a fault; call GET group-settings (400 NOT_IN_GROUP / `s… - [Link the group's collections that share a handle](https://docs.depict.ai/api-reference/link-the-groups-collections-that-share-a-handle.md): Creates a cross-store link for every collection handle present in more than one store of `merchant_id`'s group (existing links are kept), then, if the group has auto-replicate on, stamps the new links to replicate from its source. Call it after connecting a store. Requires multi-store in the plan (4… - [Set which store each collection copy replicates from](https://docs.depict.ai/api-reference/set-which-store-each-collection-copy-replicates-from.md): Sets `replication_merchant_id` on the given collection copies (null stops replicating); copies left out are unchanged. A merchant may only name stores of its own group; through an AI assistant, only the connected store itself or null. Side effect: writes mapping rows; the next publish of a source co… - [Count what this store would have to unlink before disconnecting](https://docs.depict.ai/api-reference/count-what-this-store-would-have-to-unlink-before-disconnecting.md): How many mapping rows `merchant_id` has in its group, and how many of them GET collection-mappings does not show. Call it before offering disconnect. Read-only; zeros for a store in no group. - [Delete this store's own cross-store collection links](https://docs.depict.ai/api-reference/delete-this-stores-own-cross-store-collection-links.md): Permanently deletes `merchant_id`'s own mapping rows (all, or the listed collections), which is what lets it disconnect. All or nothing: refused with 409 while another store still replicates from any of them; those stores unlink first. Never touches another store's rows. - [Which pinned products replication would skip, per replica](https://docs.depict.ai/api-reference/which-pinned-products-replication-would-skip-per-replica.md): For every replication link in `merchant_id`'s group, the source collection's pinned products that would NOT reach the replica (no SKU, SKU missing in the target store, or gone from the source). Call it to explain why a replica differs from its source. Read-only; `{edges: []}` for a store in no group… - [Who the caller is](https://docs.depict.ai/api-reference/who-the-caller-is.md): Returns the authenticated caller: Depict staff or a Shopify store user, with the emails analytics and the support widget use. No merchant needed. Read-only. - [Read a collection version's content cards](https://docs.depict.ai/api-reference/read-a-collection-versions-content-cards.md): Returns the content cards (image, video and text tiles placed in the collection's product grid) of one collection version, in stored order, read from Shopify. Each card is in the shape `PATCH /brand-features/{collection_id}` accepts, plus read-only fields PATCH ignores (`metaobject_id`, `clicks_id`,… - [Create, update or delete a collection version's brand features](https://docs.depict.ai/api-reference/create-update-or-delete-a-collection-versions-brand-features.md): Writes one kind of brand feature (content blocks, image settings, product duplicates or the legacy A/B test) for a collection version: upserts `upsert_metaobjects` as Shopify metaobjects (matched by `handle`) and deletes `delete_metaobjects_by_handle`, then records the version's feature list. Side e… - [Add, change or remove some of a collection version's content cards](https://docs.depict.ai/api-reference/add-change-or-remove-some-of-a-collection-versions-content-cards.md): Merges changes into one collection version's content cards: cards the body does not name are left exactly as they are. Read the cards first with `GET /brand-features/{collection_id}`, then send each card you change whole, as GET returned it with only your change applied: a field left out is cleared.… - [Clicks per content block in a collection over a date range](https://docs.depict.ai/api-reference/clicks-per-content-block-in-a-collection-over-a-date-range.md): Storefront clicks (and, where recorded, click and impression sessions) per content block in the collection between from_date and to_date inclusive, from Tinybird. Use it to rank content blocks by engagement. Read-only; ranges up to 365 days. - [Update one legacy A/B test metaobject](https://docs.depict.ai/api-reference/update-one-legacy-ab-test-metaobject.md): Upserts the A/B test metaobject named by the body's `handle`, creating its definitions on first use; when the body carries its `id`, it must be the path's metaobject. Used to edit a running legacy whole-collection A/B test (dates, name, notify email, generated conclusion). Side effect: a Shopify met… - [Which brand features the merchant's plan allows](https://docs.depict.ai/api-reference/which-brand-features-the-merchants-plan-allows.md): One entry per brand feature (content blocks, image settings, product duplicates, the legacy A/B test, collection-version A/B tests) saying whether the merchant's plan allows it and, if not, the upgrade reason to show. Derived from the merchant's entitlements. Read-only; cacheable for 5 minutes. - [The Instagram account connected to the merchant, if any](https://docs.depict.ai/api-reference/the-instagram-account-connected-to-the-merchant-if-any.md): Reads the stored Instagram login and asks Instagram for the account's id, name and profile picture. Returns JSON `null` when no account is connected. Read-only; one Instagram Graph call per request. - [One page of the connected Instagram account's posts](https://docs.depict.ai/api-reference/one-page-of-the-connected-instagram-accounts-posts.md): Lists the connected account's posts (newest first) with captions, permalinks, counters and album items, for picking posts into content blocks. Media URLs are short-lived signed links. Page with `next_page` = the previous `paging.cursors.after`. Read-only; one Instagram Graph call per request. - [Connect an Instagram account from an OAuth code](https://docs.depict.ai/api-reference/connect-an-instagram-account-from-an-oauth-code.md): Finishes Instagram's OAuth flow: exchanges the code for a long-lived token and stores it encrypted as the merchant's Instagram login, replacing any previous one. Only useful right after the OAuth dialog redirects back; codes are single-use. Returns JSON `null`. - [Disconnect the merchant's Instagram account](https://docs.depict.ai/api-reference/disconnect-the-merchants-instagram-account.md): Stores an Instagram config with no login, so `instagramAccount` answers `null` and `instagramMedia` 400s until an account is connected again. Instagram itself is not called. Returns JSON `null`. - [The collection templates a collection can switch between](https://docs.depict.ai/api-reference/the-collection-templates-a-collection-can-switch-between.md): Lists the collection templates in the store's published theme, marks the one this collection uses, and flags which render Depict's grid. When the Depict variant of the active template does not exist yet, a `written: false` placeholder is appended and `theme_onboarding_status` says whether Depict is… - [Set how many products per row Depict's collection grid shows](https://docs.depict.ai/api-reference/set-how-many-products-per-row-depicts-collection-grid-shows.md): Writes `[desktop_columns, mobile_columns]` to the shop metafield `$app:column-settings.column_settings` (creating its definition on first use), which Depict's theme templates read on the storefront. Side effects: a Shopify write that is live on the storefront at once, and a `colums_settings_updated`… - [Switch a collection to another theme template](https://docs.depict.ai/api-reference/switch-a-collection-to-another-theme-template.md): Sets the collection's `templateSuffix` on Shopify, which changes the live storefront page at once. Activating a Depict template (suffix starting `depict`) also marks the theme approved. Side effects: the Shopify write, a theme re-onboarding request, and a `template_activated` analytics event. Return… - [Run an allow-listed Shopify Admin GraphQL operation for the merchant](https://docs.depict.ai/api-reference/run-an-allow-listed-shopify-admin-graphql-operation-for-the-merchant.md): Forwards a GraphQL request to the merchant's Shopify Admin API with the app's stored access token. Only the portal's own allow-listed operations pass (the name and document must both match); everything else is refused. Allow-listed mutations write to the live store. Returns Shopify's GraphQL body ve… - [The merchant's public Storefront API token and store domain](https://docs.depict.ai/api-reference/the-merchants-public-storefront-api-token-and-store-domain.md): What a client needs to call the store's Storefront GraphQL API directly (e.g. to read published products and shop metafields as shoppers see them). Read-only; one config read, no Shopify call. - [List every collection of the merchant](https://docs.depict.ai/api-reference/list-every-collection-of-the-merchant.md): Returns ALL of the merchant's Shopify collections (no paging; large stores have thousands), each with its Depict state: active or not, sort order, pin count, first product images. Read-only. Prefer GET /collections/paginated for search or large stores. - [Search and page the merchant's collections](https://docs.depict.ai/api-reference/search-and-page-the-merchants-collections.md): Returns one page of the merchant's collections ordered by title, optionally filtered by a title search. Read-only. To page, pass the response's `offset` back while `has_next` is true. - [Count the merchant's active collections](https://docs.depict.ai/api-reference/count-the-merchants-active-collections.md): Returns how many collections Depict currently manages (sync_back_to_shopify on) for the merchant: the number plan limits cap. Read-only. - [Read the merchant's award notification state](https://docs.depict.ai/api-reference/read-the-merchants-award-notification-state.md): Returns which collection-milestone awards the merchant has achieved (with when) and which notifications were dismissed. Read-only; an empty state when none is saved. - [Save the merchant's award notification state](https://docs.depict.ai/api-reference/save-the-merchants-award-notification-state.md): Replaces the award state with the body (send the full state from GET /collections/award-status, modified). Side effect: appends a new config row authored by the caller. Returns null. - [Order counts per product in a collection](https://docs.depict.ai/api-reference/order-counts-per-product-in-a-collection.md): Returns `{product id: orders}` for the collection's products over [from_date, to_date], from Tinybird analytics. Products without orders are absent. Read-only. - [Revenue and sell-through per product in a collection](https://docs.depict.ai/api-reference/revenue-and-sell-through-per-product-in-a-collection.md): Returns, for every product in the collection (0 revenue when it sold nothing), revenue over [from_date, to_date] converted to the merchant's base currency (ECB rates at to_date; an unconvertible currency adds 0), and the sell-through rate. Read-only; answers from Tinybird analytics. - [Read one collection's Depict configuration](https://docs.depict.ai/api-reference/read-one-collections-depict-configuration.md): Returns the collection's configuration for a version: sort order, pinned products (for MANUAL sort, the full manual order), boost/bury rules, badges, metafield sort and product attachments. Without `version` it is the published (main) version. Read-only. 404 when the collection or the version has no… - [Save a collection's Depict configuration](https://docs.depict.ai/api-reference/save-a-collections-depict-configuration.md): The collection editor's save: writes the body as a version (a new one when `version` is null) and, with `main`, makes it the published version. Side effects: a Shopify order sync-back, replication of a main save to linked multi-store collections, and tracked events. 402 when the installation is froz… - [List a collection's versions](https://docs.depict.ai/api-reference/list-a-collections-versions.md): Returns every saved version of the collection's Depict configuration (newest first): sort, pins, rules, which one is main, market targeting and schedule. Read-only. - [Create or update a collection version](https://docs.depict.ai/api-reference/create-or-update-a-collection-version.md): Saves the body as a version of the collection without publishing it (publishing is PUT …/publish_version/{version}); `version` null or unknown creates a new version. Side effects: writes the version row, and when `is_market_active` is true deactivates the other versions of the same market or market… - [Publish a collection version to the storefront](https://docs.depict.ai/api-reference/publish-a-collection-version-to-the-storefront.md): Makes `body.version` live: as the collection's main version, or for its market / market group (retiring that market's previously live version). Writes the version's content blocks, product duplicates and image settings to Shopify metafields/metaobjects, then triggers the order sync-back. The path's… - [Unpublish a collection version](https://docs.depict.ai/api-reference/unpublish-a-collection-version.md): Takes a published version off the storefront: the main version (clears its Shopify metafields and the main pointer) or a market version (retires it for its markets); then triggers the order sync-back. The version itself is kept. - [Delete a collection version](https://docs.depict.ai/api-reference/delete-a-collection-version.md): Deletes the version: retires it from any market it is live on (a failure there is logged, not fatal), removes it from the Shopify versions metafields, and if it was main clears the main pointer and the live brand-feature metafields; then deletes the row and triggers the order sync-back. Irreversible… - [Schedule a collection version to publish later](https://docs.depict.ai/api-reference/schedule-a-collection-version-to-publish-later.md): Sets when the version is published automatically (by a cron, within minutes of the time); replaces any earlier schedule. Records the caller as the scheduler. Nothing is published now. Scheduling the main version is the normal way to time a publish of the live configuration; it is valid even when tha… - [Cancel a collection version's scheduled publish](https://docs.depict.ai/api-reference/cancel-a-collection-versions-scheduled-publish.md): Clears the version's schedule. Nothing is unpublished. - [Turn Depict on or off for one collection](https://docs.depict.ai/api-reference/turn-depict-on-or-off-for-one-collection.md): Activating makes Depict manage the collection (its saved sort, pins and rules are written back to Shopify); deactivating hands the order back to Shopify and restores the collection's template. Activating is capped by the plan's active-collection limit (402). Side effects: Shopify writes, a sync-back… - [Turn Depict on or off for many collections](https://docs.depict.ai/api-reference/turn-depict-on-or-off-for-many-collections.md): The bulk form of PUT /collections/activation for up to 100 collections. The plan limit is checked for the whole batch (402). A collection that fails (unknown, a Shopify error) is reported in `errors` and the others still apply. Returns the rollup. - [Apply one automated sort to many collections](https://docs.depict.ai/api-reference/apply-one-automated-sort-to-many-collections.md): Saves `sort_order` (plus optional collection-specific boost/bury rules) as the main version of up to 100 collections and syncs each back to Shopify; with `publish_non_live`, collections Depict did not manage yet are activated too (plan-capped, 402). Per-collection failures land in `errors`. Returns… - [The collections dashboard: a sorted, filtered page with traffic](https://docs.depict.ai/api-reference/the-collections-dashboard:-a-sorted-filtered-page-with-traffic.md): Returns one page of the merchant's collections with their traffic over [from_date, to_date] (views, clicks, CTR), ordered by traffic (`top_views`, `top_ctr`, `top_clicks`) or metadata (`updated_at`, `name_a_z`, `number_of_products`), optionally filtered by status and title. Read-only; POST because t… - [Preview a collection's products under a sort](https://docs.depict.ai/api-reference/preview-a-collections-products-under-a-sort.md): Returns the collection's products ordered as `sort_order` (and the given version's pins and rules) would order them on the storefront. The body previews unsaved rules, pins, groupings or a metafield sort; send `{}` (or null fields) to use the saved ones. Read-only despite POST. - [Read a collection's products in their current order](https://docs.depict.ai/api-reference/read-a-collections-products-in-their-current-order.md): Returns the collection's products in the order the storefront shows now (the main version's sort, pins and rules). Read-only. - [Read a collection's products in Shopify's own order](https://docs.depict.ai/api-reference/read-a-collections-products-in-shopifys-own-order.md): Returns the collection's products in the order Shopify itself holds (the manual order before Depict sorts). Read-only despite POST. - [List a collection's version A/B tests](https://docs.depict.ai/api-reference/list-a-collections-version-ab-tests.md): Returns the collection's version A/B tests (every status unless `status` narrows it), read from their Shopify metaobjects. Read-only. - [Start a collection version A/B test](https://docs.depict.ai/api-reference/start-a-collection-version-ab-test.md): Splits the collection's storefront traffic between two saved versions for 7–30 days, in every market or in the given market groups. Creates the test and per-variant orderings as Shopify metaobjects; a failure rolls them back. Needs the launch flag (403) and a Custom Merchandising plan (402); a scope… - [Read one collection version A/B test with its results](https://docs.depict.ai/api-reference/read-one-collection-version-ab-test-with-its-results.md): Returns the test plus its results so far: per-variant and per-market KPIs, B-over-A lift, significance and a daily series. Results are null before the start date or when analytics are unavailable. Read-only. - [Delete an ended collection version A/B test](https://docs.depict.ai/api-reference/delete-an-ended-collection-version-ab-test.md): Deletes a test that is no longer running, with its Shopify metaobjects. A running test must be ended first (409). No content (204). - [End a collection version A/B test, promote a winner, or refresh a variant](https://docs.depict.ai/api-reference/end-a-collection-version-ab-test-promote-a-winner-or-refresh-a-variant.md): Applies one lifecycle action (see the body). Promoting makes the variant's version the collection's main version and syncs it to Shopify. Returns the updated test. - [The merchant's market groups](https://docs.depict.ai/api-reference/the-merchants-market-groups.md): Lists the market groups (global first) with their markets and whether each group is enabled. Call it to pick the market group a collection version targets. For a Shopify caller with no groups yet, it first creates the default `global` group. - [Create a market group (or rename the group its name maps to)](https://docs.depict.ai/api-reference/create-a-market-group-or-rename-the-group-its-name-maps-to.md): Creates a group whose id is derived from `name` (lowercased, spaces and dashes to underscores) and moves the given markets into it. A name that maps to an existing id renames that group instead. Writes config.market_group and config.market; returns the group. - [The merchant's Shopify markets with their countries and currency](https://docs.depict.ai/api-reference/the-merchants-shopify-markets-with-their-countries-and-currency.md): Lists every Shopify market of the merchant, grouped or not, with its mapped countries and currency, ordered by country. Call it to offer markets when building a market group. Read-only. - [Rename a market group or replace its markets](https://docs.depict.ai/api-reference/rename-a-market-group-or-replace-its-markets.md): Renames the group when `name` is non-empty, and when `market_ids` is given replaces its markets with exactly those (removed markets go back to `global`; `[]` empties it). The `global` group cannot be modified. Writes config.market_group and config.market; returns the group. - [Enable or disable every market in a market group](https://docs.depict.ai/api-reference/enable-or-disable-every-market-in-a-market-group.md): Enables or disables Depict for all markets in the group. Disabling returns a warning with the number of active collection versions that target the group, and queues a Shopify sort sync for the merchant's active collections. Writes config.shopify_merchant_enabled_market. - [The merchant's product groupings](https://docs.depict.ai/api-reference/the-merchants-product-groupings.md): Lists every head + tails grouping defined for the merchant, for the collection editor's groupings library. Whether a grouping applies in a collection is set on the collection version (`active_attachment_ids`). Read-only. - [Define a product grouping](https://docs.depict.ai/api-reference/define-a-product-grouping.md): Creates a grouping of a head product and its ordered tails. It applies nowhere until a collection version activates it. Writes config.lite_product_attachment; returns the grouping. - [Replace a product grouping's head and tails](https://docs.depict.ai/api-reference/replace-a-product-groupings-head-and-tails.md): Replaces the grouping's head and tails; collections that activated it pick up the change. Writes config.lite_product_attachment; returns the grouping. - [Delete a product grouping](https://docs.depict.ai/api-reference/delete-a-product-grouping.md): Deletes the grouping and removes it from every collection version that activated it. Idempotent: deleting a missing grouping is also a 204. Writes config.lite_product_attachment and config.lite_collection_version. - [Changelog](https://docs.depict.ai/changelog/shopify-lite.md): New features and improvements in Depict: Search & Merchandising. ## OpenAPI Specs - [lite](/api-reference/openapi/lite.json) - [portal](/api-reference/openapi/portal.json) - [storefront](/api-reference/openapi/storefront.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.