Better Data

Api Reference

Create and Apply Forecast Events

Edit this page

Create and Apply Forecast Events

This guide shows you how to create a promotional event and apply it to a forecast scenario to adjust demand predictions.

Prerequisites

  • API Key: Valid API key with forecast.write permission
  • Organization Access: Access to your organization's forecasting features
  • Product ID: Product master ID for product-specific events (optional)
  • Location ID: Location ID for location-specific events (optional)

Step-by-Step Guide

Step 1: Create an External Event

Create a promotional event that will drive demand adjustments.

Request:

1curl -X POST "https://app.betterdata.co/api/forecast/events" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Summer Sale 2024",
6    "type": "PROMOTION",
7    "startsAt": "2024-06-01T00:00:00Z",
8    "endsAt": "2024-06-30T23:59:59Z",
9    "value": {
10      "liftPct": 0.25,
11      "stackingMode": "MULTIPLICATIVE",
12      "description": "25% lift during summer sale promotion"
13    },
14    "productMasterId": "prod_123"
15  }'

Response:

1{
2  "id": "event_789",
3  "name": "Summer Sale 2024",
4  "type": "PROMOTION",
5  "startsAt": "2024-06-01T00:00:00Z",
6  "endsAt": "2024-06-30T23:59:59Z",
7  "value": {
8    "liftPct": 0.25,
9    "stackingMode": "MULTIPLICATIVE"
10  },
11  "isGlobal": false,
12  "isOrgWide": true,
13  "productMaster": {
14    "id": "prod_123",
15    "name": "Product Name",
16    "sku": "SKU-123"
17  },
18  "createdAt": "2024-03-15T00:00:00Z"
19}

Notes:

  • Event Types: PROMOTION, PRICE_CHANGE, HOLIDAY, WEATHER, BOOKING, MACRO, OTHER
  • Lift Percentage: Range from -0.99 (99% reduction) to 5 (500% increase)
  • Stacking Mode:
    • MULTIPLICATIVE: Events multiply together (e.g., 1.25 × 1.15 = 1.4375)
    • ADDITIVE: Events add together (e.g., 0.25 + 0.15 = 0.40)
  • Global Events: Set productMasterId to null for organization-wide events
  • Org-Wide Events: Set locationId to null for location-agnostic events

Step 2: Create or Select a Forecast Scenario

Create a new forecast scenario or use an existing one.

Request:

1curl -X POST "https://app.betterdata.co/api/forecast/scenarios" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Q2 2024 with Promotions",
6    "description": "Forecast including summer sale promotion",
7    "type": "PROMOTIONAL",
8    "assumptions": {
9      "narrative": "Q2 includes major promotional campaign",
10      "includedEventIds": ["event_789"]
11    }
12  }'

Response:

1{
2  "scenario": {
3    "id": "scenario_456",
4    "name": "Q2 2024 with Promotions",
5    "description": "Forecast including summer sale promotion",
6    "type": "PROMOTIONAL",
7    "status": "DRAFT",
8    "createdAt": "2024-03-15T00:00:00Z"
9  }
10}

Notes:

  • Scenario Types: BASELINE, PROMOTIONAL, CONSERVATIVE, OPTIMISTIC, CHANNEL_LAUNCH, CUSTOM
  • Event Inclusion: Add event IDs to includedEventIds array
  • Multiple Events: Include multiple events to model complex scenarios

Step 3: Generate Forecasts for the Scenario

Generate forecasts that incorporate the event.

Request:

1curl -X POST "https://app.betterdata.co/api/forecast/scenarios/scenario_456/generate" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "productMasterIds": ["prod_123"],
6    "locationIds": ["loc_123"],
7    "horizonDays": 90,
8    "forceRegenerate": false
9  }'

Response:

1{
2  "success": true,
3  "generated": 1,
4  "forecasts": [
5    {
6      "productMasterId": "prod_123",
7      "locationId": "loc_123",
8      "horizonDays": 90,
9      "generatedAt": "2024-03-15T12:00:00Z"
10    }
11  ]
12}

Notes:

  • Horizon Days: Forecast period (7-365 days)
  • Force Regenerate: Set to true to regenerate existing forecasts
  • Selective Generation: Specify productMasterIds and locationIds to limit scope

Step 4: Verify Event Impact

Check the forecast change history to see how the event affected forecasts.

Request:

1curl -X GET "https://app.betterdata.co/api/forecast/change-history?productMasterId=prod_123&locationId=loc_123&changeTypes=EVENT_APPLIED" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json"

Response:

1{
2  "entries": [
3    {
4      "id": "change_123",
5      "changeType": "EVENT_APPLIED",
6      "eventId": "event_789",
7      "eventName": "Summer Sale 2024",
8      "beforeValue": 100,
9      "afterValue": 125,
10      "changePercent": 25,
11      "timestamp": "2024-03-15T12:00:00Z"
12    }
13  ],
14  "total": 1,
15  "hasMore": false
16}

Complete Example

Here's a complete workflow combining all steps:

1#!/bin/bash
2 
3API_KEY="YOUR_API_KEY"
4BASE_URL="https://app.betterdata.co/api"
5 
6# Step 1: Create event
7EVENT_RESPONSE=$(curl -s -X POST "${BASE_URL}/forecast/events" \
8  -H "Authorization: Bearer ${API_KEY}" \
9  -H "Content-Type: application/json" \
10  -d '{
11    "name": "Summer Sale 2024",
12    "type": "PROMOTION",
13    "startsAt": "2024-06-01T00:00:00Z",
14    "endsAt": "2024-06-30T23:59:59Z",
15    "value": {
16      "liftPct": 0.25,
17      "stackingMode": "MULTIPLICATIVE"
18    }
19  }')
20 
21EVENT_ID=$(echo $EVENT_RESPONSE | jq -r '.id')
22echo "Created event: $EVENT_ID"
23 
24# Step 2: Create scenario
25SCENARIO_RESPONSE=$(curl -s -X POST "${BASE_URL}/forecast/scenarios" \
26  -H "Authorization: Bearer ${API_KEY}" \
27  -H "Content-Type: application/json" \
28  -d "{
29    \"name\": \"Q2 2024 with Promotions\",
30    \"type\": \"PROMOTIONAL\",
31    \"assumptions\": {
32      \"includedEventIds\": [\"${EVENT_ID}\"]
33    }
34  }")
35 
36SCENARIO_ID=$(echo $SCENARIO_RESPONSE | jq -r '.scenario.id')
37echo "Created scenario: $SCENARIO_ID"
38 
39# Step 3: Generate forecasts
40curl -X POST "${BASE_URL}/forecast/scenarios/${SCENARIO_ID}/generate" \
41  -H "Authorization: Bearer ${API_KEY}" \
42  -H "Content-Type: application/json" \
43  -d '{
44    "horizonDays": 90
45  }'
46 
47echo "Forecasts generated successfully"

Idempotency Notes

  • Event Creation: Creating an event with the same name and date range will create a new event (not idempotent). Use event IDs to track which events you've already created.
  • Scenario Generation: Generating forecasts for the same scenario multiple times will update existing forecasts unless forceRegenerate is set to false and forecasts already exist.
  • Event Application: Events are applied during forecast generation. Regenerating forecasts will reapply events.

Pagination Notes

  • List Events: The events list endpoint supports pagination with page and limit parameters (default: 20, max: 100).
  • Change History: The change history endpoint uses limit and offset for pagination (default: 50, max: 100).

Common Issues

Event Not Applied

Symptom: Event created but forecast doesn't reflect the lift.

Solutions:

  1. Verify event is included in scenario's includedEventIds
  2. Check event date range overlaps with forecast period
  3. Ensure forecasts were generated after event was created
  4. Verify event productMasterId and locationId match forecast scope

Invalid Lift Percentage

Symptom: Error when creating event with lift percentage.

Solutions:

  1. Ensure liftPct is between -0.99 and 5
  2. Use decimal format (0.25 for 25%, not 25)
  3. Check stackingMode is either MULTIPLICATIVE or ADDITIVE

Forecast Generation Fails

Symptom: Error when generating forecasts.

Solutions:

  1. Verify scenario status is DRAFT or PUBLISHED (not ARCHIVED)
  2. Check product and location IDs are valid
  3. Ensure horizonDays is between 7 and 365
  4. Verify you have forecast.write permission

Permissions & Roles

Creating events and scenarios requires forecast.write permission. Generating forecasts requires ADMIN, MANAGER, or PLANNER role.