Derive Size Profile From Sales History
POST/api/merchandising/size-profiles/derive
Build a product-scoped size profile from a matrix parent's variant sales mix over a history window. The curve has ONE entry per size: variants that share a size across colours are combined. Entries are in the size run's natural order (e.g. 0-3m, 3-6m … 2T, 3T, 4T, 5T, 6, 7, 8, 10 … XS, S, M, L, XL), not alphabetical.
inventory:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body:
- parent_product_id (required, integer): a matrix parent product
- window_days (required, integer 1–1095): how many days of sales to read
- in_stock_correction (optional, boolean): weight each size by its rate of sale per in-stock day, so sold-out best sellers are not under-weighted
- full_price_only (optional, boolean): with in_stock_correction, leave out discounted sales lines (ignored without it)
- preview (optional, boolean): when true, return the derived curve (200) WITHOUT saving it; otherwise it is saved (201)
- name (optional, string, max 255): name for the saved profile (defaults to "<style name> Size Curve")
Returns 422 with an actionable message when the product is not a matrix parent, has no variants, or has no (full-price) variant sales in the window.
Response fields (saved, 201): id, name, scope_type, scope_id, scope_label ("SKU — product name"), derived_from_window_days, source (derived or derived_in_stock_corrected), entries (id, size_label, share_pct, sort_order), total_share_pct, created_at, updated_at. Response fields (preview, 200): name, scope_type, scope_id, scope_label, derived_from_window_days, source, in_stock_correction, full_price_only, entries (size_label, share_pct, sort_order), total_share_pct.
Requires a Bearer token with the inventory read/write scope.
Request
Responses
- 200
- 201
- 401
- 403
- 422
- 429
OK
Response Headers
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.