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

# One product's sales and grid performance over a date range

> 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 shop currency.



## OpenAPI

````yaml /api-reference/openapi/lite.json get /products/{product_id}/analytics
openapi: 3.1.0
info:
  title: Search & Merchandising API
  version: 1.0.0
  description: >-
    REST API behind Depict: Search & Merchandising, the native Shopify app:
    onboarding, collections, boost & bury, dashboards, A/B testing and
    multi-store management. Endpoints are served under the /api/lite prefix and
    are authenticated with the Shopify session token that App Bridge issues to
    the embedded app.
servers:
  - url: /api/lite
security:
  - ShopifySessionToken: []
paths:
  /products/{product_id}/analytics:
    get:
      summary: One product's sales and grid performance over a date range
      description: >-
        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 shop currency.
      operationId: productAnalytics
      parameters:
        - schema:
            type: string
            description: Shopify product id (numeric string).
          required: true
          description: Shopify product id (numeric string).
          name: product_id
          in: path
        - schema:
            type: string
            description: Lite merchant id, e.g. `shopify-<shop id>`.
          required: true
          description: Lite merchant id, e.g. `shopify-<shop id>`.
          name: merchant_id
          in: query
        - schema:
            type: string
            format: date
            description: First day, inclusive.
          required: true
          description: First day, inclusive.
          name: from_date
          in: query
        - schema:
            type: string
            format: date
            description: Last day, inclusive.
          required: true
          description: Last day, inclusive.
          name: to_date
          in: query
        - schema:
            type:
              - number
              - 'null'
            description: >-
              A positive value replaces the catalogue's top score as the score
              scale (used when fetching a comparison period).
          required: false
          description: >-
            A positive value replaces the catalogue's top score as the score
            scale (used when fetching a comparison period).
          name: score_reference
          in: query
        - schema:
            type: string
            description: Restrict to one market (or market group); omit for all markets.
          required: false
          description: Restrict to one market (or market group); omit for all markets.
          name: market_id
          in: query
      responses:
        '200':
          description: The analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductAnalyticsResponse'
        '400':
          description: >-
            The query failed its schema, from_date is after to_date, or the
            range exceeds 365 days.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '403':
          description: Authenticated, but this identity may not call the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '404':
          description: Merchant not found for this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
components:
  schemas:
    ProductAnalyticsResponse:
      type: object
      properties:
        currency:
          type: string
          description: Shop currency every amount is in.
        kpis:
          $ref: '#/components/schemas/ProductAnalyticsKpis'
        series:
          $ref: '#/components/schemas/ProductAnalyticsSeries'
        collections:
          type: array
          items:
            $ref: '#/components/schemas/ProductAnalyticsCollection'
        revenue_rank:
          anyOf:
            - $ref: '#/components/schemas/ProductRevenueRank'
            - type: 'null'
        partial_metrics:
          type: object
          additionalProperties:
            type: string
          description: >-
            Metric name → why it is incomplete (e.g. a data source was
            unavailable).
        score_reference:
          type:
            - number
            - 'null'
      required:
        - currency
        - kpis
        - series
        - collections
    Detail:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
      description: 'Every 4xx/5xx body: `{detail}`.'
    ProductAnalyticsKpis:
      type: object
      properties:
        revenue:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        units:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        conversion:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        plp_views:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        plp_clicks:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        add_to_carts:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        score:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
        position:
          $ref: '#/components/schemas/ProductAnalyticsKpi'
      required:
        - revenue
        - units
        - conversion
        - plp_views
        - plp_clicks
        - add_to_carts
        - score
    ProductAnalyticsSeries:
      type: object
      properties:
        dates:
          type: array
          items:
            type: string
        revenue:
          type: array
          items:
            type: number
        units:
          type: array
          items:
            type: number
        add_to_carts:
          type:
            - array
            - 'null'
          items:
            type: number
        position:
          type:
            - array
            - 'null'
          items:
            type: number
        position_by_collection:
          type:
            - object
            - 'null'
          additionalProperties:
            type: array
            items:
              type: number
          description: Collection id → one value per date.
        score:
          type:
            - array
            - 'null'
          items:
            type: number
        plp_views:
          type:
            - array
            - 'null'
          items:
            type: number
        plp_views_by_collection:
          type:
            - object
            - 'null'
          additionalProperties:
            type: array
            items:
              type: number
          description: Collection id → one value per date.
        plp_clicks:
          type:
            - array
            - 'null'
          items:
            type: number
        plp_clicks_by_collection:
          type:
            - object
            - 'null'
          additionalProperties:
            type: array
            items:
              type: number
          description: Collection id → one value per date.
      required:
        - dates
        - revenue
        - units
      description: Daily values aligned with `dates`.
    ProductAnalyticsCollection:
      type: object
      properties:
        collection_id:
          type: string
        name:
          type: string
        image_url:
          type:
            - string
            - 'null'
        position:
          type: integer
          description: The product's position in the grid.
        n_products:
          type: integer
        clicks:
          type: integer
        views:
          type:
            - integer
            - 'null'
        ctr:
          type:
            - number
            - 'null'
        pinned:
          type: boolean
        live:
          type: boolean
      required:
        - collection_id
        - name
        - image_url
        - position
        - n_products
        - clicks
        - views
        - ctr
    ProductRevenueRank:
      type: object
      properties:
        rank:
          type: integer
        products:
          type: integer
        beats:
          type: integer
        buckets:
          type: array
          items:
            type: number
        product_bucket:
          type: integer
        bucket_edges:
          type: array
          items:
            type: number
        daily:
          type: array
          items:
            type: integer
          description: >-
            The product's rank on each of `series.dates` (0 = no sales that
            day); absent when the daily rank read returned nothing.
      required:
        - rank
        - products
        - beats
        - buckets
        - product_bucket
        - bucket_edges
      description: Where the product's revenue ranks in the catalogue.
    ProductAnalyticsKpi:
      type: object
      properties:
        value:
          type:
            - number
            - 'null'
        prev_value:
          type:
            - number
            - 'null'
          description: The same KPI over the preceding period of equal length.
  securitySchemes:
    ShopifySessionToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Shopify App Bridge session token of the embedded Depict: Search &
        Merchandising app. The shop in the token determines the merchant;
        merchant_id parameters must belong to that shop.

````