Retrieve Product Metrics

GET /api/v1/products/metrics

Description

Retrieves detailed metrics for products, allowing for extensive analysis based on grouping, time ranges, and other filtering criteria. This endpoint is essential for business intelligence, inventory management, and strategic planning.

Headers:

• tenantId (required): The tenant ID under which the product metrics are being queried. This should be included as a header.
• userId (required): The user ID of the individual querying the product metrics. This should also be included as a header.
• countryCode (required): The country code where the products are registered or being analyzed. This should be included as a header.

Query Parameters:

• groupBy (optional): Specifies the criteria for grouping the results. Possible values include CREATED_BY, DELETED_BY, UPDATED_BY, PRODUCT_ID, PRODUCT_USER, TRADE_PRODUCT_ID, TRADE_STATE, TRADE_CITY, TRADE_BUYER, TRADE_SELLER. Values should be separated by commas.
• metricDateRange (optional): Filters metrics by a specific date range. Format: start_date,end_date (e.g., 2020-11-12,2022-11-15).
• byValueType (optional): Specifies the type of value range used for filtering metrics, required when byValue is used. Available values: HOUR, DAY, DAY_OF_WEEK, WEEK, MONTH.
• byValue (optional): A numerical value to filter metrics when used in conjunction with byValueType.
• productSearch (optional): A general search term to filter the metrics based on product details.
• productLowStock (optional): A threshold number to filter products with low stock levels.
• productQuantity (optional): Filters products by quantity available.
• productByProductTypeIds (optional): Filters metrics based on product type IDs.
• productIds (optional): Filters metrics based on specific product IDs.
• productActive (optional): Filters products based on active status. Available values: 0 (inactive), 1 (active).
• byStates (optional): Filters products by states.
• byCities (optional): Filters products by cities.
• byBusinessIds (optional): Filters metrics by business IDs.

Example Request:

curl -G "http://[base_url]/api/v1/products/metrics" \
     -H "Authorization: Bearer [access_token]" \
     -H "tenantId: TEN123" \
     -H "userId: USR456" \
     -H "countryCode: US" \
     -d "groupBy=PRODUCT_ID,TRADE_CITY" \
     -d "metricDateRange=2020-11-12,2022-11-15" \
     -d "byValueType=MONTH" \
     -d "byValue=3" \
     -d "productSearch=apple" \
     -d "productLowStock=10" \
     -d "productQuantity=50" \
     -d "productByProductTypeIds=123" \
     -d "productIds=1001" \
     -d "productActive=1" \
     -d "byStates=California" \
     -d "byCities=San Francisco" \
     -d "byBusinessIds=BIZ123"

Responses:

• 200 OK: Successfully retrieved the product metrics. The response includes detailed data about the products that match the specified criteria, potentially including sales trends, inventory levels, and other relevant metrics.

Example Response:

{
  "metrics": [
    {
      "groupBy": "PRODUCT_ID",
      "data": [
        {
          "productId": "1001",
          "productName": "Organic Apple",
          "city": "San Francisco",
          "totalSales": 500,
          "remainingStock": 50
        }
      ]
    }
  ]
}

Error Responses:

• 400 Bad Request: Incorrect or incomplete query parameters.
• 404 Not Found: No metrics found based on the provided criteria.
• 403 Forbidden: The user does not have permission to view the metrics.