Create Product Substitution
POST/api/products/:productId/substitutions
Create a substitution rule: the route product is the original, the payload names the substitute.
products:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token.
Validation rejects self-substitution, duplicate pairs, non-stock-tracked substitutes, and always rules that would close an automatic swap loop. create_reverse also creates the independent reverse rule (substitute → original) with the same mode and substitution_type.
A non-blocking warning is returned when the pair mixes a serialised and a non-serialised product.
substitution_type classifies what kind of substitute this is — direct (identical to the customer, just a different SKU) or replacement (does the same job but is visibly different, so the customer receives something other than what they ordered). It is optional and defaults to direct. It is orthogonal to mode: substitution_type says what the substitute is, mode says when the swap may fire.
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.