Product modifiers
Which modifier groups a product has, in order, with its selection rule and option surcharges by variant.
Product modifiers
Objects
ProductModifierGroups
product_idintegerrequiredID of the product. The groups are versioned on its card: ETag and If-Match carry the product version.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
groupsarray of objectrequiredThe product modifier groups in display order. On write, the whole set.
Fields · 2
group_idintegerrequiredID of the modifier group (/v1/modifier-groups).
selection_ruleobject or nullrequiredSelection rule on this product instead of the group rule; null — the group rule.
Fields · 2
min_selectintegerrequiredHow many options must be chosen on this product.
max_selectinteger or nullrequiredHow many options can be chosen on this product; null — no limit.
option_pricesarray of objectrequiredSurcharge and availability of options on the product variants instead of the option surcharge. On write, replaces the overrides as a whole; without the field the previous ones stay, except those of removed groups.
Fields · 4
option_idintegerrequiredID of an option from the product groups.
variant_idintegerrequiredID of the product variant.
is_availablebooleanrequiredfalse — the option is not offered on this variant; such a row has no surcharge.
price_deltainteger or nullrequiredOption surcharge on this variant, an integer in minor units of the store currency; null only for an unavailable option.
Endpoints
Get the product modifier groups and their option surcharges by variant
get/products/{product}/modifier-groups
Scope: catalog:read
Parameters
Path
productintegerrequiredID of the product.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns ProductModifierGroups
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/products/{product}/modifier-groups" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"product_id": 0,
"version": 0,
"groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"option_prices": [
{
"option_id": 0,
"variant_id": 0,
"is_available": true,
"price_delta": 0
}
]
}Replace the product modifier groups and their option surcharges by variant
put/products/{product}/modifier-groups
Scope: catalog:write
Parameters
Path
productintegerrequiredID of the product.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
groupsarray of objectrequiredThe product modifier groups in display order. On write, the whole set.
- Max items:
- 50
- No repeats
Fields · 2
group_idintegerrequiredID of the modifier group (/v1/modifier-groups).
selection_ruleobject or nullSelection rule on this product instead of the group rule; null — the group rule.
Fields · 2
min_selectintegerHow many options must be chosen on this product.
- Minimum:
- 0
- Maximum:
- 99
max_selectinteger or nullHow many options can be chosen on this product; null — no limit.
- Minimum:
- 1
- Maximum:
- 99
option_pricesarray of objectSurcharge and availability of options on the product variants instead of the option surcharge. On write, replaces the overrides as a whole; without the field the previous ones stay, except those of removed groups.
- Max items:
- 2000
Fields · 4
option_idintegerrequiredID of an option from the product groups.
is_availablebooleanrequiredfalse — the option is not offered on this variant; such a row has no surcharge.
price_deltainteger or nullOption surcharge on this variant, an integer in minor units of the store currency; null only for an unavailable option.
- Minimum:
- -100000000
- Maximum:
- 100000000
variant_idintegerrequiredID of the product variant.
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns ProductModifierGroups
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PUT "https://api.saleya.app/v1/products/{product}/modifier-groups" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 1
}
}
],
"option_prices": [
{
"option_id": 0,
"is_available": true,
"price_delta": 0,
"variant_id": 0
}
]
}{
"product_id": 0,
"version": 0,
"groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"option_prices": [
{
"option_id": 0,
"variant_id": 0,
"is_available": true,
"price_delta": 0
}
]
}