{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/athenahq-ai/json-schema/athenahq-ai-shopping-metrics-data-schema.json",
  "title": "ShoppingMetricsData",
  "description": "The Shopping Insights dashboard blocks. Rates are percentages 0-100; positions are 1-based (lower is better).",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/athenahq-ai-openapi.json#/components/schemas/ShoppingMetricsData",
  "type": "object",
  "required": [
    "summary",
    "offer_summary",
    "top_own_products",
    "top_competitor_products",
    "competitor_breakdown",
    "merchant_breakdown",
    "position_distribution",
    "price_comparison",
    "trend"
  ],
  "properties": {
    "summary": {
      "type": "object",
      "description": "Headline counts across every shopping answer in the range",
      "required": [
        "total_shopping_responses",
        "responses_with_own_products",
        "appearance_rate",
        "total_products",
        "own_products",
        "competitor_products",
        "avg_own_position",
        "avg_competitor_position"
      ],
      "properties": {
        "total_shopping_responses": {
          "type": "integer",
          "description": "Responses that included a product carousel"
        },
        "responses_with_own_products": {
          "type": "integer",
          "description": "Shopping answers that included at least one of the brand's products"
        },
        "appearance_rate": {
          "type": "number",
          "description": "responses_with_own_products / total_shopping_responses as a percentage 0-100"
        },
        "total_products": {
          "type": "integer",
          "description": "Product appearances across all shopping answers"
        },
        "own_products": {
          "type": "integer",
          "description": "Appearances of the brand's own products"
        },
        "competitor_products": {
          "type": "integer",
          "description": "Appearances attributed to tracked competitors"
        },
        "avg_own_position": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average carousel position of the brand's products"
        },
        "avg_competitor_position": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average carousel position of competitor products"
        }
      }
    },
    "offer_summary": {
      "type": "object",
      "description": "Retail offers (price listings) attached to the products in the range",
      "required": [
        "total_offers",
        "products_with_offers",
        "competitor_offers",
        "currency",
        "avg_price"
      ],
      "properties": {
        "total_offers": {
          "type": "integer",
          "description": "Offers attached to the brand's products"
        },
        "products_with_offers": {
          "type": "integer",
          "description": "Brand product appearances that carried at least one offer"
        },
        "competitor_offers": {
          "type": "integer",
          "description": "Offers attached to competitor products"
        },
        "currency": {
          "type": "string",
          "description": "Currency of avg_price (the most common offer currency)"
        },
        "avg_price": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average offer price of the brand's products"
        }
      }
    },
    "top_own_products": {
      "type": "array",
      "description": "The brand's most frequently shown products, most appearances first",
      "items": {
        "$ref": "#/$defs/ShoppingProduct"
      }
    },
    "top_competitor_products": {
      "type": "array",
      "description": "Competitor products shown most often, most appearances first",
      "items": {
        "$ref": "#/$defs/ShoppingCompetitorProduct"
      }
    },
    "competitor_breakdown": {
      "type": "array",
      "description": "Competitor leaderboard: which tracked competitors show up most in shopping answers",
      "items": {
        "type": "object",
        "required": [
          "competitor_id",
          "competitor_name",
          "product_count",
          "avg_position",
          "avg_rating",
          "response_count"
        ],
        "properties": {
          "competitor_id": {
            "type": "string",
            "format": "uuid"
          },
          "competitor_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Competitor name"
          },
          "product_count": {
            "type": "integer",
            "description": "Product appearances attributed to the competitor"
          },
          "avg_position": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average carousel position of the competitor's products; null when no appearance carried a position"
          },
          "avg_rating": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average rating shown for the competitor's products"
          },
          "response_count": {
            "type": "integer",
            "description": "Shopping answers the competitor appeared in"
          }
        }
      }
    },
    "merchant_breakdown": {
      "type": "array",
      "description": "Retailer breakdown: where products are stocked in AI answers, own versus competitor",
      "items": {
        "type": "object",
        "required": [
          "merchant",
          "own_count",
          "competitor_count",
          "own_avg_position",
          "competitor_avg_position",
          "own_response_count",
          "competitor_response_count"
        ],
        "properties": {
          "merchant": {
            "type": "string"
          },
          "own_count": {
            "type": "integer",
            "description": "Brand product appearances listed from this retailer"
          },
          "competitor_count": {
            "type": "integer",
            "description": "Competitor product appearances listed from this retailer"
          },
          "own_avg_position": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average position of the brand's products from this retailer"
          },
          "competitor_avg_position": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average position of competitor products from this retailer"
          },
          "own_response_count": {
            "type": "integer",
            "description": "Shopping answers with a brand product from this retailer"
          },
          "competitor_response_count": {
            "type": "integer",
            "description": "Shopping answers with a competitor product from this retailer"
          }
        }
      }
    },
    "position_distribution": {
      "type": "array",
      "description": "Rank distribution: who occupies each carousel position",
      "items": {
        "type": "object",
        "required": [
          "position",
          "count",
          "own_count",
          "competitor_count"
        ],
        "properties": {
          "position": {
            "type": "integer",
            "description": "1-based carousel position"
          },
          "count": {
            "type": "integer",
            "description": "Product appearances at this position"
          },
          "own_count": {
            "type": "integer",
            "description": "Brand product appearances at this position"
          },
          "competitor_count": {
            "type": "integer",
            "description": "Competitor product appearances at this position"
          }
        }
      }
    },
    "price_comparison": {
      "type": "array",
      "description": "Offer price range for the brand's products versus competitors, per currency",
      "items": {
        "type": "object",
        "required": [
          "category",
          "currency",
          "avg_price",
          "min_price",
          "max_price",
          "product_count"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "own",
              "competitor"
            ]
          },
          "currency": {
            "type": "string"
          },
          "avg_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average offer price"
          },
          "min_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lowest offer price"
          },
          "max_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Highest offer price"
          },
          "product_count": {
            "type": "integer",
            "description": "Product appearances with a parseable price"
          }
        }
      }
    },
    "trend": {
      "type": "array",
      "description": "Daily product appearances, own versus competitor",
      "items": {
        "type": "object",
        "required": [
          "date",
          "total_products",
          "own_products",
          "competitor_products",
          "total_responses",
          "responses_with_own"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "total_products": {
            "type": "integer"
          },
          "own_products": {
            "type": "integer"
          },
          "competitor_products": {
            "type": "integer"
          },
          "total_responses": {
            "type": "integer",
            "description": "Shopping answers that day"
          },
          "responses_with_own": {
            "type": "integer",
            "description": "Shopping answers that day with a brand product"
          }
        }
      }
    }
  },
  "$defs": {
    "ShoppingCompetitorProduct": {
      "type": "object",
      "required": [
        "title",
        "merchant",
        "appearances",
        "avg_position",
        "avg_rating",
        "image_url",
        "product_url",
        "competitor_id"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "Product title as shown in the shopping answer"
        },
        "merchant": {
          "type": [
            "string",
            "null"
          ],
          "description": "Retailer the product was listed from, when the answer named one"
        },
        "appearances": {
          "type": "integer",
          "description": "Number of shopping answers the product appeared in"
        },
        "avg_position": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average 1-based position in the carousel (lower is better); null when no appearance carried a position"
        },
        "avg_rating": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average rating shown for the product, when any"
        },
        "image_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Product image URL from the answer"
        },
        "product_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Product page URL from the answer"
        },
        "competitor_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Competitor the product was attributed to"
        }
      }
    },
    "ShoppingProduct": {
      "type": "object",
      "required": [
        "title",
        "merchant",
        "appearances",
        "avg_position",
        "avg_rating",
        "image_url",
        "product_url"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "Product title as shown in the shopping answer"
        },
        "merchant": {
          "type": [
            "string",
            "null"
          ],
          "description": "Retailer the product was listed from, when the answer named one"
        },
        "appearances": {
          "type": "integer",
          "description": "Number of shopping answers the product appeared in"
        },
        "avg_position": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average 1-based position in the carousel (lower is better); null when no appearance carried a position"
        },
        "avg_rating": {
          "type": [
            "number",
            "null"
          ],
          "description": "Average rating shown for the product, when any"
        },
        "image_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Product image URL from the answer"
        },
        "product_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Product page URL from the answer"
        }
      }
    }
  }
}