List Fulfillment Recommendations

Beta
GET/v1/operations/fulfillment-recommendations

This endpoint is idempotent. Learn more

Returns, for every sellable SKU, whether it should be built to stock or only against orders — and the measurement that decided.

The rules are ordered and the first match wins. Lead-time feasibility is checked before anything else: if customers are promised less time than production needs, building to order is not possible rather than not preferred, and no amount of lumpy demand changes that. After that the engine looks for dead stock, a single contract customer, demand too erratic for a buffer to size, and slow-moving expensive units.

Every verdict carries its numbers — demand interval, variability, customer concentration, promised lead time, annual cost of goods — so a planner can disagree with the rule rather than only with the answer. Thresholds are merchant-editable in the planning settings.

Computed fresh on every call rather than stored. A recommendation is only meaningful next to current demand, and a saved one would go quietly stale; the durable artifact is the item setting written when someone agrees with it. Nothing here changes a plan on its own.

Permissions requiredValues:production_schedules:read
The role behind your API key or agent must grant every one of these permissions.
objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of fulfillment_recommendation

Resources in this page.

objectstringenumValues:fulfillment_recommendation

Resource type identifier.

itementitynullable

The item the advice is about.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

skustring

SKU of that item.

product_lineentitynullable

The product line it sells under, when it sells under one.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

current_policystringenumValues:make_to_stockmake_to_order

How the item is planned today.

recommended_policystringenumValues:make_to_stockmake_to_order

How the engine thinks it should be planned.

changesboolean

Whether adopting the recommendation would change anything.

reasonstringenumValues:lead_time_infeasibleno_recent_demandsingle_customer

The rule that decided.

  • lead_time_infeasible: customers are promised less time than production needs, so the stock has to exist before the order does. Checked first, because producing to order is not possible rather than not preferred.
  • no_recent_demand: nothing has sold for long enough that a buffer is dead stock.
  • single_customer: effectively one customer buys it, and that customer is served to order.
  • lumpy_demand: demand arrives rarely and in wildly different sizes, which is the shape a safety stock sizes worst.
  • slow_moving_high_value: expensive units, few sold — the buffer costs more than the service it buys.
  • steady_demand: regular enough to forecast, which is what stocking is for.
average_demand_intervalnumber

Months observed divided by months with demand: 1 means it sells every month, 3 means once a quarter on average.

Measured on monthly buckets, which cannot distinguish two orders in one month from one.

coefficient_of_variationnumber

Squared coefficient of variation over the months that had demand, measuring how uneven the quantities are.

top_customer_share_pctnumber

The largest customer's share of this item's demand, as a percentage.

top_customer_namestringnullable

Name of that customer.

demand_weighted_lead_time_daysnumber

Calendar days customers are promised on average, weighted by how much each buys.

annual_cogsnumber

Annual cost of goods for this item: demand times unit cost.

months_since_last_saleinteger

Months since anything last sold, capped at the observation window.

mixed_stream_share_pctnumber

Percentage of demand from customers whose own stated policy disagrees with the recommendation.

A policy is resolved per SKU, so an item sold to both a stocking distributor and a contract customer gets one answer either way. A high share here is the signal that the single answer is uncomfortable.

Responses

200

Successful response for List Fulfillment Recommendations