List opportunity forecasts

GET /2024-09/forecasting/opportunity-forecasts

Default

Get the list of marketplace opportunity forecasts with filtering options.

Query parameters

merchant_id string(uuid) Required

The UUID of the merchant to filter forecasts by
id string(uuid)

Filter by specific forecast ID
minimum_profit number

Minimum profit amount to filter by (uses risk-adjusted high forecast)

Minimum value is 0.
maximum_margin_percent number

Maximum margin percentage to filter by

Minimum value is 0, maximum value is 100.
marketplace_catalog_item_id string(uuid)

Filter by marketplace catalog item ID
supplier_item_cost_id string(uuid)

Filter by supplier item cost ID
page integer

The page number to retrieve

Minimum value is 1.
per_page integer

The number of results to return per page

Minimum value is 1, maximum value is 100.

Responses

200 application/json

A successful response returning the list of opportunity forecasts
Hide response attributes Show response attributes object
- links object
  
  Hide links attributes Show links attributes object
  
  first string
  
  last string
  
  prev string | null
  
  next string | null
- meta object
  
  Hide meta attributes Show meta attributes object
  
  current_page integer
  
  from integer | null
  
  last_page integer
  
  path string
  
  per_page integer
  
  to integer | null
  
  total integer
- data array[object] Required
  
  Calculated marketplace opportunity forecast with risk assessment
  
  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

GET /2024-09/forecasting/opportunity-forecasts

curl \
 --request GET 'https://app.merchanthq.com/api/2024-09/forecasting/opportunity-forecasts?merchant_id=1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "links": {
    "first": "https://app.merchanthq.com/api/2024-09/merchants?page=1",
    "last": "https://app.merchanthq.com/api/2024-09/merchants?page=10",
    "prev": "https://app.merchanthq.com/api/2024-09/merchants?page=1",
    "next": "https://app.merchanthq.com/api/2024-09/merchants?page=3"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "path": "https://app.merchanthq.com/api/2024-09/merchants",
    "per_page": 10,
    "to": 10,
    "total": 20
  },
  "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"
}