Apply or Schedule a Recipe Change
POST/api/v2/products/:product/component-revisions
Apply a recipe change to a bundle or kit effective as-of a date. When effective_from is today the change applies to the live recipe immediately; a future date is SCHEDULED (the live recipe stays unchanged until that day, when a daily job flips it); a past date is a CORRECTION that rewrites what historical orders resolved to in that window and therefore requires allow_backdate=true. If the band covering that date already carries exactly this recipe nothing is written and mode is UNCHANGED.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Dates are calendar days in the account's timezone. Only bundle and kit products accept a recipe.
Fields:
- components (required, array, min 1): each { id (product id, unique within the list), quantity (>= 1) }.
- effective_from (required, date YYYY-MM-DD): the day the new recipe takes effect.
- change_summary (optional, string, max 1000): note stored on the revision.
- allow_backdate (optional, boolean): must be true when effective_from is in the past, else the request is rejected.
Authentication: Requires Bearer token.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
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.