{
  "components": {
    "schemas": {
      "SalesFreshness": {
        "properties": {
          "as_of": {
            "format": "date-time",
            "type": "string"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "fresh": {
            "type": "boolean"
          },
          "generation": {
            "type": "string"
          },
          "source_read_concern": {
            "enum": [
              "snapshot"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "SalesGeography": {
        "properties": {
          "country_code": {
            "type": "string"
          },
          "depot_code": {
            "type": "string"
          },
          "market_code": {
            "type": "string"
          },
          "state_code": {
            "type": "string"
          }
        },
        "required": [
          "country_code"
        ],
        "type": "object"
      },
      "SalesItem": {
        "properties": {
          "market_code": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          },
          "sales_performance": {
            "$ref": "#/components/schemas/SalesMetrics"
          },
          "sku_code": {
            "type": "string"
          }
        },
        "required": [
          "sku_code",
          "market_code",
          "sales_performance"
        ],
        "type": "object"
      },
      "SalesMetrics": {
        "properties": {
          "as_of": {
            "format": "date-time",
            "type": "string"
          },
          "category_ranks": {
            "items": {
              "properties": {
                "category_tag_code": {
                  "type": "string"
                },
                "net_units": {
                  "format": "int64",
                  "minimum": 0,
                  "type": "integer"
                },
                "population": {
                  "minimum": 0,
                  "type": "integer"
                },
                "rank": {
                  "minimum": 1,
                  "type": "integer"
                },
                "window_days": {
                  "enum": [
                    7
                  ],
                  "type": "integer"
                }
              },
              "required": [
                "category_tag_code",
                "rank",
                "window_days",
                "population",
                "net_units"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "last_30_days": {
            "$ref": "#/components/schemas/SalesWindow"
          },
          "last_7_days": {
            "$ref": "#/components/schemas/SalesWindow"
          },
          "last_90_days": {
            "$ref": "#/components/schemas/SalesWindow"
          },
          "last_sold_at": {
            "format": "date-time",
            "type": "string"
          },
          "lifetime": {
            "$ref": "#/components/schemas/SalesTotals"
          },
          "timezone": {
            "enum": [
              "Australia/Melbourne"
            ],
            "type": "string"
          }
        },
        "required": [
          "as_of",
          "timezone",
          "last_7_days",
          "last_30_days",
          "last_90_days",
          "lifetime",
          "category_ranks"
        ],
        "type": "object"
      },
      "SalesQuery": {
        "additionalProperties": false,
        "properties": {
          "barcode": {
            "type": "string"
          },
          "brand_code": {
            "type": "string"
          },
          "brand_slug": {
            "type": "string"
          },
          "category_slug": {
            "type": "string"
          },
          "category_tag_code": {
            "type": "string"
          },
          "channel": {
            "enum": [
              "retail",
              "wholesale",
              "staff"
            ],
            "type": "string"
          },
          "collection_code": {
            "type": "string"
          },
          "collection_slug": {
            "type": "string"
          },
          "generation": {
            "type": "string"
          },
          "geography": {
            "items": {
              "$ref": "#/components/schemas/SalesGeography"
            },
            "maxItems": 100,
            "type": "array"
          },
          "has_preorder_policy": {
            "type": "boolean"
          },
          "lifecycle_tag": {
            "enum": [
              "NEW",
              "RESTOCKED"
            ],
            "type": "string"
          },
          "limit": {
            "maximum": 200,
            "minimum": 1,
            "type": "integer"
          },
          "market_code": {
            "type": "string"
          },
          "offset": {
            "minimum": 0,
            "type": "integer"
          },
          "on_promotion": {
            "type": "boolean"
          },
          "page": {
            "default": 1,
            "minimum": 1,
            "type": "integer"
          },
          "page_size": {
            "default": 20,
            "maximum": 200,
            "minimum": 1,
            "type": "integer"
          },
          "preorder_available": {
            "type": "boolean"
          },
          "ranking_generation": {
            "description": "Pin the preceding page; a changed generation returns conflict.",
            "type": "string"
          },
          "search": {
            "type": "string"
          },
          "sku_codes": {
            "items": {
              "type": "string"
            },
            "maxItems": 1000,
            "type": "array"
          },
          "sku_series_code": {
            "type": "string"
          },
          "soon_expiry": {
            "type": "boolean"
          },
          "soon_expiry_policy_open": {
            "type": "boolean"
          },
          "sort": {
            "description": "Metric sorts default descending; '+' selects ascending and '-' descending. Catalogue sorts default ascending with SKU tie-breaking. Supports last7_days_net_units, last30_days_net_units, last90_days_net_units, lifetime_net_units, lifetime_paid_order_count, last_sold_at, popularity, best_selling, best_sellers, sku_code, name, status, sku_series_code, updated_at. Name uses Supply's canonical primary name.",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "draft",
              "archived",
              "discontinued"
            ],
            "type": "string"
          },
          "storage_type": {
            "type": "string"
          },
          "supplier_code": {
            "type": "string"
          },
          "view": {
            "enum": [
              "",
              "top_picks",
              "category",
              "category_top_10",
              "no_sales"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "SalesResult": {
        "properties": {
          "as_of": {
            "format": "date-time",
            "type": "string"
          },
          "catalogue_generation": {
            "type": "string"
          },
          "generation": {
            "type": "string"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SalesItem"
            },
            "maxItems": 200,
            "type": "array"
          },
          "market_code": {
            "type": "string"
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "pricing_generation": {
            "type": "string"
          },
          "ranking_generation": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "generation",
          "catalogue_generation",
          "pricing_generation",
          "ranking_generation",
          "as_of",
          "timezone",
          "market_code",
          "total",
          "page",
          "page_size",
          "items"
        ],
        "type": "object"
      },
      "SalesTotals": {
        "properties": {
          "gross_units": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "net_units": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "paid_order_count": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "refunded_units": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "paid_order_count",
          "gross_units",
          "refunded_units",
          "net_units"
        ],
        "type": "object"
      },
      "SalesWindow": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SalesTotals"
          },
          {
            "properties": {
              "window_days": {
                "enum": [
                  7,
                  30,
                  90
                ],
                "type": "integer"
              }
            },
            "required": [
              "window_days"
            ],
            "type": "object"
          }
        ]
      },
      "github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem": {
        "properties": {
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "ProductSalesBearerAuth": {
        "bearerFormat": "JWT",
        "description": "Workforce product.read with current Identity session and geographic grants, only for product analytics.",
        "scheme": "bearer",
        "type": "http"
      },
      "ProductSalesServiceAuth": {
        "bearerFormat": "JWT",
        "description": "Exact svc-supply service token with product-sales:read.",
        "scheme": "bearer",
        "type": "http"
      },
      "PubSubPushOIDCAuth": {
        "bearerFormat": "OIDC",
        "description": "Google Cloud Pub/Sub push OIDC token verified against EVENTS_PUSH_AUDIENCE and EVENTS_ALLOWED_SA_EMAILS.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "externalDocs": {
    "description": "",
    "url": ""
  },
  "info": {
    "contact": {
      "name": "Potato Mart Platform Team"
    },
    "description": "Potato Mart Backend-Insights service. Consumes\norder/payment/refund analytical facts into a strict typed\nfact store. Event-delivery failures use RFC 9457 problem\ndetails; successful event deliveries return 204. Accepted analytical schemas\nare analytics.order_fact v5, analytics.payment_fact v2, and\nanalytics.refund_fact v5. Order/refund package compositions require full\nimmutable package_option objects (sku_code, code, positive version), with\neach reference SKU matching the enclosing item and code matching its physical\nsnapshot as EACH or CASE followed by the positive units count. Legacy scalar references\nand earlier order/refund versions fail closed. Operational payment.captured\nv2 is acknowledged without interpreting capture_timing or storing a fact.\nAnalytics fact timestamps are producer facts, never inferred exact capture\ntimes. Catalogue product analytics have narrowly scoped workforce APIs;\ndenormalized source geography is retained without inferred paths or authority.",
    "license": {
      "name": "Proprietary"
    },
    "title": "Backend-Insights API",
    "version": "39.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/livez": {
      "get": {
        "description": "Reports that the service process can handle HTTP requests. Does not check MongoDB connectivity.",
        "operationId": "getLiveness",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "service": {
                      "const": "backend-insights",
                      "type": "string"
                    },
                    "status": {
                      "const": "ok",
                      "type": "string"
                    },
                    "version": {
                      "description": "Linked Shared Contract version.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "service",
                    "version"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The service is running."
          }
        },
        "security": [],
        "summary": "Check process liveness",
        "tags": [
          "health"
        ]
      },
      "servers": [
        {
          "url": "/"
        }
      ]
    },
    "/product-sales/freshness": {
      "get": {
        "description": "Requires complete fresh Orders and catalogue evidence. Workforce requests require product.read, live session introspection and geographic scope. Service queries require exact svc-supply and product-sales:read. Enabled by PRODUCT_SALES_ENABLED.",
        "operationId": "getProductSalesFreshness",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SalesFreshness"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Verified sales evidence and generation identities"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "504": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          }
        },
        "security": [
          {
            "ProductSalesBearerAuth": []
          }
        ],
        "summary": "getProductSalesFreshness",
        "tags": [
          "product-sales"
        ]
      }
    },
    "/product-sales/query": {
      "post": {
        "description": "Requires complete fresh Orders and catalogue evidence. Workforce requests require product.read, live session introspection and geographic scope. Service queries require exact svc-supply and product-sales:read. Enabled by PRODUCT_SALES_ENABLED.",
        "operationId": "queryStaffProductSales",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SalesQuery"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SalesResult"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Verified sales evidence and generation identities"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "504": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          }
        },
        "security": [
          {
            "ProductSalesBearerAuth": []
          }
        ],
        "summary": "queryStaffProductSales",
        "tags": [
          "product-sales"
        ]
      }
    },
    "/readyz": {
      "get": {
        "description": "Checks MongoDB connectivity with a two-second timeout before reporting readiness.",
        "operationId": "getReadiness",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "status": {
                      "const": "ready",
                      "type": "string"
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The service can reach its database."
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "The database is unavailable."
          }
        },
        "security": [],
        "summary": "Check service readiness",
        "tags": [
          "health"
        ]
      },
      "servers": [
        {
          "url": "/"
        }
      ]
    },
    "/storefront/product-sales/query": {
      "post": {
        "description": "Requires complete fresh Orders and catalogue evidence. Workforce requests require product.read, live session introspection and geographic scope. Service queries require exact svc-supply and product-sales:read. Enabled by PRODUCT_SALES_ENABLED.",
        "operationId": "queryPublicProductSales",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SalesQuery"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SalesResult"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Verified sales evidence and generation identities"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "504": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          }
        },
        "security": [],
        "summary": "queryPublicProductSales",
        "tags": [
          "product-sales"
        ]
      }
    },
    "/storefront/rankings/categories/{categoryCode}": {
      "get": {
        "description": "Requires complete fresh Orders and catalogue evidence. Workforce requests require product.read, live session introspection and geographic scope. Service queries require exact svc-supply and product-sales:read. Enabled by PRODUCT_SALES_ENABLED.",
        "operationId": "getCategorySales",
        "parameters": [
          {
            "in": "query",
            "name": "market_code",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "page_size",
            "schema": {
              "default": 20,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Pin subsequent pages to the first response; a changed generation returns 409.",
            "in": "query",
            "name": "ranking_generation",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "categoryCode",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SalesResult"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Verified sales evidence and generation identities"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "504": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          }
        },
        "security": [],
        "summary": "getCategorySales",
        "tags": [
          "product-sales"
        ]
      }
    },
    "/storefront/rankings/top-picks": {
      "get": {
        "description": "Requires complete fresh Orders and catalogue evidence. Workforce requests require product.read, live session introspection and geographic scope. Service queries require exact svc-supply and product-sales:read. Enabled by PRODUCT_SALES_ENABLED.",
        "operationId": "getTopPicks",
        "parameters": [
          {
            "in": "query",
            "name": "market_code",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "page_size",
            "schema": {
              "default": 20,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Pin subsequent pages to the first response; a changed generation returns 409.",
            "in": "query",
            "name": "ranking_generation",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SalesResult"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Verified sales evidence and generation identities"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          },
          "504": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Insights_internal_platform_httpapi.Problem"
                }
              }
            },
            "description": "Request rejected or required owner evidence unavailable"
          }
        },
        "security": [],
        "summary": "getTopPicks",
        "tags": [
          "product-sales"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "/v1"
    }
  ]
}