Developer docs

← All endpoints

PUT/v1/tenants/{tenantId}/demand_planning/sales_forecast_batches/{batchId}

Upload a batch of sales forecasts Experimental

The batch id is generated by the client. Retrying the same id with the same payload is safe and returns 200 with the existing status; the same id with a different payload is a 409. The body may be gzip-compressed (Content-Encoding: gzip). Format errors are reported as a 400 that lists every problem with its path in the document; nothing is stored in that case. Whether stores and SKUs exist is checked when the batch is processed and reported per item in the batch status. Limits are published at GET /limits. A corrected batch is a new run: new batch id, newer generatedAt, and its own batchIndex/batchTotal (or none). Send batches sequentially; the per-client rate limit makes parallel uploads no faster.

Parameters

tenantIdpathstringnon-nullrequired
batchIdpathstringnon-nullrequired

Client-generated UUID for this batch

Content-Encodingheaderstringnon-nulloptional

gzip when the body is compressed

Request body (required)

application/jsonobjectnon-null

A batch of sales forecasts from one planning run

batchIndexintegernullableoptional

1-based position of this batch within the run. Set together with batchTotal or not at all.

  • Format: int32
Example12
batchTotalintegernullableoptional

Number of batches in the run

  • Format: int32
Example140
extdictionary of objectnullableoptional

Partner-owned fields. Never interpreted by Snowbee.

Show dictionary values

Each dictionary key maps to objectnon-null.

generatedAtstringnon-nullrequired

Timestamp of the planning run that produced every item in the batch. Identical for all batches of one run; a later run must have a later value.

  • Format: ISO 8681 timestamp
Example"2026-08-28T03:12:00Z"
itemCountintegernon-nullrequired

Must equal the length of items

  • Format: int32
Example5000
itemsarray of objectnon-nullrequired
Show item fields

Sales forecast for one store and SKU. The item replaces the whole forecast held for that store and SKU.

ecomStoreNumberstringnullableoptional

Ecom store number. Exactly one of retailStoreNumber and ecomStoreNumber must be set.

Example"9001"
extdictionary of objectnullableoptional

Partner-owned fields. Never interpreted by Snowbee.

Show dictionary values

Each dictionary key maps to objectnon-null.

horizonEndDatestringnon-nullrequired

Last forecast day, an ISO 8601 calendar date. Must equal horizonStartDate plus quantities.length - 1 days; catches horizons of the wrong length.

  • Format: date
Example"2026-09-30"
horizonStartDatestringnon-nullrequired

First forecast day, an ISO 8601 calendar date. No earlier than 7 days ago.

  • Format: date
Example"2026-09-01"
quantitiesarray of stringnon-nullrequired

Expected gross sales quantity per day from horizonStartDate to horizonEndDate inclusive, as decimal strings with at most 4 decimals. quantities[i] is the forecast for horizonStartDate plus i days.

Example["4.7","3.1","0","5.25"]
retailStoreNumberstringnullableoptional

Retail store number. Exactly one of retailStoreNumber and ecomStoreNumber must be set.

Example"1001"
skuNumberstringnon-nullrequired
Example"10025"

View schema definition

Responses

200Response

Same batch already stored

application/jsonobjectnon-null
batchIdstringnon-nullrequired

Client-generated batch id

Example"0192a3b4-5c6d-7e8f-9012-3456789abcde"
batchIndexintegernullableoptional
  • Format: int32
Example12
batchKindstringnon-nullrequired
Allowed values"SALES_FORECAST""REPLENISHMENT_PARAMETERS"
batchTotalintegernullableoptional
  • Format: int32
Example140
completedTimestringnullableoptional
  • Format: ISO 8681 timestamp
Example"2025-10-28T12:37:42Z"
countsobjectnullableoptional

Null until the batch has been processed

Show child fields
apiUpdatesDisabledintegernon-nullrequired

Items skipped because the retail store is not set to take updates from the API in Snowbee (replenishment parameters only)

  • Format: int32
Example0
appliedintegernon-nullrequired

Items written to Snowbee

  • Format: int32
Example4996
itemsintegernon-nullrequired
  • Format: int32
Example5000
lockedintegernon-nullrequired

Items skipped because the line is locked in Snowbee (replenishment parameters only)

  • Format: int32
Example0
rejectedintegernon-nullrequired

Items not applied; listed in rejectedItems

  • Format: int32
Example4
supersededintegernon-nullrequired

Items skipped because a newer generatedAt was already applied for the same key

  • Format: int32
Example0
unchangedintegernon-nullrequired

Items skipped because they match the values the store already uses (replenishment parameters only)

  • Format: int32
Example0
errorMessagestringnullableoptional

Why the batch FAILED

generatedAtstringnon-nullrequired
  • Format: ISO 8681 timestamp
Example"2026-08-28T03:12:00Z"
itemCountintegernon-nullrequired
  • Format: int32
Example5000
progressstringnon-nullrequired
Allowed values"PENDING""PROCESSING""COMPLETED""COMPLETED_WITH_REJECTED_ITEMS""FAILED"
receivedTimestringnon-nullrequired

When Snowbee stored the batch

  • Format: ISO 8681 timestamp
Example"2026-08-28T03:12:04.120Z"
rejectedItemsarray of objectnullableoptional

First rejected items; null until processed. See rejectedItemsTruncated.

Show item fields
codestringnon-nullrequired

One of: UNKNOWN_RETAIL_STORE, RETAIL_STORE_NOT_RELEASED, UNKNOWN_ECOM_STORE, ECOM_STORE_NOT_RELEASED, UNKNOWN_SKU, SKU_NOT_IN_ASSORTMENT, REPLENISHMENT_TYPE_MANUAL

Example"UNKNOWN_SKU"
ecomStoreNumberstringnullableoptional
Example"9001"
indexintegernon-nullrequired

0-based index into items

  • Format: int32
Example17
messagestringnullableoptional
retailStoreNumberstringnullableoptional
Example"1001"
skuNumberstringnullableoptional
Example"10025"
rejectedItemsTruncatedbooleannon-nullrequired

True when more items were rejected than are listed

Examplefalse
startedTimestringnullableoptional
  • Format: ISO 8681 timestamp
Example"2025-10-28T12:37:42Z"
warningsarray of objectnullableoptional

Warnings recorded at receipt and during processing

Show item fields

A non-fatal observation about the batch

codestringnon-nullrequired

UNKNOWN_FIELD: a field Snowbee does not know and did not apply

Example"UNKNOWN_FIELD"
countintegernullableoptional

How many times the observation occurred

  • Format: int32
Example5000
fieldstringnullableoptional

Path of the field, with [] for array elements

Example"items[].campaignQuantity"
messagestringnullableoptional

View schema definition

202Response

New batch stored

application/jsonobjectnon-null
batchIdstringnon-nullrequired

Client-generated batch id

Example"0192a3b4-5c6d-7e8f-9012-3456789abcde"
batchIndexintegernullableoptional
  • Format: int32
Example12
batchKindstringnon-nullrequired
Allowed values"SALES_FORECAST""REPLENISHMENT_PARAMETERS"
batchTotalintegernullableoptional
  • Format: int32
Example140
completedTimestringnullableoptional
  • Format: ISO 8681 timestamp
Example"2025-10-28T12:37:42Z"
countsobjectnullableoptional

Null until the batch has been processed

Show child fields
apiUpdatesDisabledintegernon-nullrequired

Items skipped because the retail store is not set to take updates from the API in Snowbee (replenishment parameters only)

  • Format: int32
Example0
appliedintegernon-nullrequired

Items written to Snowbee

  • Format: int32
Example4996
itemsintegernon-nullrequired
  • Format: int32
Example5000
lockedintegernon-nullrequired

Items skipped because the line is locked in Snowbee (replenishment parameters only)

  • Format: int32
Example0
rejectedintegernon-nullrequired

Items not applied; listed in rejectedItems

  • Format: int32
Example4
supersededintegernon-nullrequired

Items skipped because a newer generatedAt was already applied for the same key

  • Format: int32
Example0
unchangedintegernon-nullrequired

Items skipped because they match the values the store already uses (replenishment parameters only)

  • Format: int32
Example0
errorMessagestringnullableoptional

Why the batch FAILED

generatedAtstringnon-nullrequired
  • Format: ISO 8681 timestamp
Example"2026-08-28T03:12:00Z"
itemCountintegernon-nullrequired
  • Format: int32
Example5000
progressstringnon-nullrequired
Allowed values"PENDING""PROCESSING""COMPLETED""COMPLETED_WITH_REJECTED_ITEMS""FAILED"
receivedTimestringnon-nullrequired

When Snowbee stored the batch

  • Format: ISO 8681 timestamp
Example"2026-08-28T03:12:04.120Z"
rejectedItemsarray of objectnullableoptional

First rejected items; null until processed. See rejectedItemsTruncated.

Show item fields
codestringnon-nullrequired

One of: UNKNOWN_RETAIL_STORE, RETAIL_STORE_NOT_RELEASED, UNKNOWN_ECOM_STORE, ECOM_STORE_NOT_RELEASED, UNKNOWN_SKU, SKU_NOT_IN_ASSORTMENT, REPLENISHMENT_TYPE_MANUAL

Example"UNKNOWN_SKU"
ecomStoreNumberstringnullableoptional
Example"9001"
indexintegernon-nullrequired

0-based index into items

  • Format: int32
Example17
messagestringnullableoptional
retailStoreNumberstringnullableoptional
Example"1001"
skuNumberstringnullableoptional
Example"10025"
rejectedItemsTruncatedbooleannon-nullrequired

True when more items were rejected than are listed

Examplefalse
startedTimestringnullableoptional
  • Format: ISO 8681 timestamp
Example"2025-10-28T12:37:42Z"
warningsarray of objectnullableoptional

Warnings recorded at receipt and during processing

Show item fields

A non-fatal observation about the batch

codestringnon-nullrequired

UNKNOWN_FIELD: a field Snowbee does not know and did not apply

Example"UNKNOWN_FIELD"
countintegernullableoptional

How many times the observation occurred

  • Format: int32
Example5000
fieldstringnullableoptional

Path of the field, with [] for array elements

Example"items[].campaignQuantity"
messagestringnullableoptional

View schema definition

400Validation failed; details is a SbPublicApiValidationErrorDetails

Validation failed; details is a SbPublicApiValidationErrorDetails

application/jsonobjectnon-null
detailsobjectnullableoptional

Structured details; shape depends on error

errorstringnon-nullrequired
Example"VALIDATION_ERROR"
messagestringnon-nullrequired

Human-readable error message

Example"3 of 5000 items failed validation"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the invalid items and retry the complete batch"

View schema definition

401Response
application/jsonobjectnon-null
errorstringnon-nullrequired

Stable error code

Example"INVALID_REQUEST"
messagestringnon-nullrequired

Human-readable error message

Example"Invalid customer ID format"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the customer ID and retry the request"

View schema definition

403Response
application/jsonobjectnon-null
errorstringnon-nullrequired

Stable error code

Example"INVALID_REQUEST"
messagestringnon-nullrequired

Human-readable error message

Example"Invalid customer ID format"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the customer ID and retry the request"

View schema definition

409Batch id already used with a different payload

Batch id already used with a different payload

application/jsonobjectnon-null
errorstringnon-nullrequired

Stable error code

Example"INVALID_REQUEST"
messagestringnon-nullrequired

Human-readable error message

Example"Invalid customer ID format"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the customer ID and retry the request"

View schema definition

413A limit was exceeded; details is a SbPublicApiLimitExceededDetails

A limit was exceeded; details is a SbPublicApiLimitExceededDetails

application/jsonobjectnon-null
detailsobjectnullableoptional

Structured details; shape depends on error

errorstringnon-nullrequired
Example"VALIDATION_ERROR"
messagestringnon-nullrequired

Human-readable error message

Example"3 of 5000 items failed validation"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the invalid items and retry the complete batch"

View schema definition

415Content-Type must be application/json

Content-Type must be application/json

application/jsonobjectnon-null
errorstringnon-nullrequired

Stable error code

Example"INVALID_REQUEST"
messagestringnon-nullrequired

Human-readable error message

Example"Invalid customer ID format"
resolutionstringnon-nullrequired

Suggested next action

Example"Correct the customer ID and retry the request"

View schema definition