MerchantHQ API
POST /2024-09/forecasting/opportunity-forecasts/calculate
Default

Calculate a new forecast for an inventory opportunity based on marketplace catalog item and supplier item cost.

application/json

Body Required

  • marketplace_catalog_item_id string(uuid) Required

    The UUID of the marketplace catalog item

  • supplier_item_cost_id string(uuid) Required

    The UUID of the supplier item cost

Responses

  • 201 application/json

    A successful response returning the calculated opportunity forecast

    Hide response attribute Show response attribute object
    • data object Required

      Calculated marketplace opportunity forecast with risk assessment

      Additional properties are NOT allowed.

      Hide data attributes Show data attributes object
      • id string(uuid) Required

        The UUID of the resource.

      • marketplace_catalog_item_id string(uuid) Required

        The UUID of the marketplace catalog item

      • supplier_item_cost_id string(uuid) Required

        The UUID of the supplier item cost

      • thirty_day_profit_forecast_high object Required

        High estimate for 30-day profit forecast

        Additional properties are NOT allowed.

        Hide thirty_day_profit_forecast_high attributes Show thirty_day_profit_forecast_high attributes object
        • value number Required

          The numeric value of the high profit forecast

        • currency string Required

          The currency code (e.g., USD, EUR)

      • thirty_day_profit_forecast_low object Required

        Low estimate for 30-day profit forecast

        Additional properties are NOT allowed.

        Hide thirty_day_profit_forecast_low attributes Show thirty_day_profit_forecast_low attributes object
        • value number Required

          The numeric value of the low profit forecast

        • currency string Required

          The currency code (e.g., USD, EUR)

      • risk_score integer Required

        Risk score from 1-100

        Minimum value is 1, maximum value is 100.

      • risk_factors array[string] Required

        List of risk factors identified

        Values are limited_price_history, highly_variable_price_history, multiple_sellers_1_to_3, multiple_sellers_3_to_10, multiple_sellers_10_to_20, multiple_sellers_over_20, brand_protected_single_seller, restricted_category_medical, restricted_category_food, restricted_category_clothing, restricted_category_electronics, restricted_category_household, requires_compliance_documentation, low_review_volume, low_review_rating_under_4_5, low_review_rating_under_4, low_review_rating_under_3_5, low_review_rating_under_3, fake_reviews_detected, low_margins_under_20_percent, low_margins_under_10_percent, low_margins_under_5_percent, low_supplier_stock_under_2_months, low_supplier_stock_under_1_month, or low_supplier_stock_under_1_week.

      • risk_adjusted_thirty_day_profit_forecast_high object Required

        Risk-adjusted high estimate for 30-day profit forecast

        Additional properties are NOT allowed.

        Hide risk_adjusted_thirty_day_profit_forecast_high attributes Show risk_adjusted_thirty_day_profit_forecast_high attributes object
        • value number Required

          The numeric value of the risk-adjusted high profit forecast

        • currency string Required

          The currency code (e.g., USD, EUR)

      • risk_adjusted_thirty_day_profit_forecast_low object Required

        Risk-adjusted low estimate for 30-day profit forecast

        Additional properties are NOT allowed.

        Hide risk_adjusted_thirty_day_profit_forecast_low attributes Show risk_adjusted_thirty_day_profit_forecast_low attributes object
        • value number Required

          The numeric value of the risk-adjusted low profit forecast

        • currency string Required

          The currency code (e.g., USD, EUR)

      • calculated_at string(date-time) Required

        The date and time the resource was created.

      • type string

        The type of opportunity forecasted

      • forecast_model string Required

        Name and version of the forecast model used

      • forecast_inputs object Required

        JSON object containing the inputs used for the forecast calculation

      • created_at string(date-time) Required

        The date and time the resource was created.

      • updated_at string(date-time) Required

        The date and time the resource was last updated.
  • 401 application/json

    The request requires user authentication or the user is not authorized to access this resource.

    Hide response attribute Show response attribute object
    • message string
  • 404 application/json

    The specified resource was not found

    Hide response attribute Show response attribute object
    • message string
  • 422 application/json

    The request was unprocessable due to validation errors

    Hide response attributes Show response attributes object
    • message string Required
    • errors object Required

      A map of field names to arrays of error messages

      Hide errors attribute Show errors attribute object
      • * array[string] Additional properties
POST /2024-09/forecasting/opportunity-forecasts/calculate 
curl \
 --request POST 'https://app.merchanthq.com/api/2024-09/forecasting/opportunity-forecasts/calculate' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"marketplace_catalog_item_id":"1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4","supplier_item_cost_id":"2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4"}'
Request examples 
{
  "marketplace_catalog_item_id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
  "supplier_item_cost_id": "2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4"
}
Response examples (201) 
{
  "data": {
    "id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "marketplace_catalog_item_id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "supplier_item_cost_id": "2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "thirty_day_profit_forecast_high": {
      "value": 42.0,
      "currency": "string"
    },
    "thirty_day_profit_forecast_low": {
      "value": 42.0,
      "currency": "string"
    },
    "risk_score": 35,
    "risk_factors": [
      "limited_price_history"
    ],
    "risk_adjusted_thirty_day_profit_forecast_high": {
      "value": 42.0,
      "currency": "string"
    },
    "risk_adjusted_thirty_day_profit_forecast_low": {
      "value": 42.0,
      "currency": "string"
    },
    "calculated_at": "2025-01-10T10:37:11Z",
    "type": "beat_lowest_recent_price",
    "forecast_model": "beat_lowest_recent_price_opportunity_forecast_v150725",
    "forecast_inputs": {},
    "created_at": "2025-01-10T10:37:11Z",
    "updated_at": "2025-01-10T10:37:11Z"
  }
}
Response examples (401) 
{
  "message": "Unauthorized"
}
Response examples (404) 
{
  "message": "Not found"
}
Response examples (422) 
{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field name field is required."
    ]
  }
}