Modifier groups
Choices for an item: sauces, extras, portion size. The group sets the selection bounds, options set surcharge and composition.
Modifier groups
Objects
ModifierGroup
idintegerrequiredID of the record, unique among records of its kind in the store.
external_idstring or nullrequiredExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
namemap of stringrequiredName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
min_selectintegerrequiredHow many options the customer must choose: 0 — the group is optional. A product can set its own rule (selection_rule).
max_selectinteger or nullrequiredHow many options can be chosen in total, repeats included; null — no limit.
is_activebooleanrequiredfalse — the group is turned off and not offered on products.
adds_ingredientsbooleanrequiredWhether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).
optionsarray of objectrequiredOptions in display order. On write, the whole set: a row finds its option by id or external_id, the found one gets the fields sent, a row without an option is new and carries name; an option missing from the set is archived and removed from open draft orders.
Fields · 12
idintegerrequiredID of the record, unique among records of its kind in the store.
external_idstring or nullrequiredExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
nameobjectrequiredName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
price_deltaintegerrequiredSurcharge on the item price per portion of the option, an integer in minor units of the store currency; negative — a discount. A product can set its own surcharge by variant.
max_quantityinteger or nullrequiredHow many times the option can be taken in one item; null — no own limit, only the group max_select applies.
duration_minutesinteger or nullrequiredHow many minutes the option adds to a bookable service, a multiple of 5; null — none. Has no effect on other kinds of items.
is_activebooleanrequiredfalse — the option is turned off and not offered.
is_defaultbooleanrequiredThe option is preselected: the storefront and the POS check it at once, and the server fills a required group left empty with it.
adds_ingredientsboolean or nullrequiredWhether this option changes the composition; null — as the group (adds_ingredients).
recipe_per_variantbooleanrequiredConsumption depends on the dish: no general composition, the amount is set by the recipe of each variant (option_recipes); without it the option is not offered on that variant.
nutritionobject or nullrequiredNutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.
Fields · 4
kcalintegerrequiredEnergy, kcal.
protein_mgintegerrequiredProtein, mg.
fat_mgintegerrequiredFat, mg.
carbs_mgintegerrequiredCarbohydrates, mg.
recipearray of objectrequiredGeneral composition of the option — what it consumes in any dish: ingredients and preps with their amount. Empty for a per-dish option. On write, the whole list, an empty one clears it; without the field the composition is left as it is.
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste: in the composition but not consumed.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
deleted_atstring (date-time) or nullrequiredWhen the record was archived; null for a live record.
Endpoints
List modifier groups with options changed since the given moment
get/modifier-groups
Scope: catalog:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
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
410The sync cursor is older than the deletion retention period or was issued before the database was restored
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
Errors of this endpoint
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/modifier-groups" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Create a modifier group with options
post/modifier-groups
Scope: catalog:write
Parameters
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
Request body application/json
namemap of string or nullrequiredName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
min_selectintegerHow many options the customer must choose: 0 — the group is optional. A product can set its own rule (selection_rule).
- Minimum:
- 0
- Maximum:
- 99
max_selectinteger or nullHow many options can be chosen in total, repeats included; null — no limit.
- Minimum:
- 1
- Maximum:
- 99
is_activebooleanfalse — the group is turned off and not offered on products.
adds_ingredientsbooleanWhether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).
optionsarray of objectrequiredOptions in display order. On write, the whole set: a row finds its option by id or external_id, the found one gets the fields sent, a row without an option is new and carries name; an option missing from the set is archived and removed from open draft orders.
- Min items:
- 1
- Max items:
- 100
- No repeats
Fields · 11
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
price_deltaintegerSurcharge on the item price per portion of the option, an integer in minor units of the store currency; negative — a discount. A product can set its own surcharge by variant.
- Minimum:
- -100000000
- Maximum:
- 100000000
max_quantityinteger or nullHow many times the option can be taken in one item; null — no own limit, only the group max_select applies.
- Minimum:
- 1
- Maximum:
- 99
duration_minutesinteger or nullHow many minutes the option adds to a bookable service, a multiple of 5; null — none. Has no effect on other kinds of items.
- Minimum:
- 5
- Maximum:
- 120
is_activebooleanfalse — the option is turned off and not offered.
is_defaultbooleanThe option is preselected: the storefront and the POS check it at once, and the server fills a required group left empty with it.
adds_ingredientsboolean or nullWhether this option changes the composition; null — as the group (adds_ingredients).
recipe_per_variantbooleanConsumption depends on the dish: no general composition, the amount is set by the recipe of each variant (option_recipes); without it the option is not offered on that variant.
nutritionobject or nullNutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.
Fields · 4
kcalintegerEnergy, kcal.
- Minimum:
- 0
- Maximum:
- 1000000
protein_mgintegerProtein, mg.
- Minimum:
- 0
- Maximum:
- 100000000
fat_mgintegerFat, mg.
- Minimum:
- 0
- Maximum:
- 100000000
carbs_mgintegerCarbohydrates, mg.
- Minimum:
- 0
- Maximum:
- 100000000
recipearray of objectGeneral composition of the option — what it consumes in any dish: ingredients and preps with their amount. Empty for a per-dish option. On write, the whole list, an empty one clears it; without the field the composition is left as it is.
- Max items:
- 100
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste: in the composition but not consumed.
- Max length:
- 32
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
Responses
201Created
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"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns ModifierGroup
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
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
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
Errors of this endpoint
- 409
external_id_archivedThe record with this external ID is archived - 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 409
record_limit_reachedThe record limit is reached - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
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 POST "https://api.saleya.app/v1/modifier-groups" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 1,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"external_id": "string",
"name": {
"key": "string"
},
"price_delta": 0,
"max_quantity": 1,
"duration_minutes": 5,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"external_id": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Get a modifier group with its options
get/modifier-groups/{group}
Scope: catalog:read
Parameters
Path
groupintegerrequiredID of the modifier group.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns ModifierGroup
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/modifier-groups/{group}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Update a modifier group and its option set
patch/modifier-groups/{group}
Scope: catalog:write
Parameters
Path
groupintegerrequiredID of the modifier group.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 1
modifier_product_minimumstringProducts with their own selection rule get a minimum equal to the number of enabled options of the group; otherwise they could not be bought.
- Min length:
- 64
- Max length:
- 64
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
optionsarray of objectOptions in display order. On write, the whole set: a row finds its option by id or external_id, the found one gets the fields sent, a row without an option is new and carries name; an option missing from the set is archived and removed from open draft orders.
- Min items:
- 1
- Max items:
- 100
- No repeats
Fields · 12
idintegerID of the record, unique among records of its kind in the store.
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
price_deltaintegerSurcharge on the item price per portion of the option, an integer in minor units of the store currency; negative — a discount. A product can set its own surcharge by variant.
- Minimum:
- -100000000
- Maximum:
- 100000000
max_quantityinteger or nullHow many times the option can be taken in one item; null — no own limit, only the group max_select applies.
- Minimum:
- 1
- Maximum:
- 99
duration_minutesinteger or nullHow many minutes the option adds to a bookable service, a multiple of 5; null — none. Has no effect on other kinds of items.
- Minimum:
- 5
- Maximum:
- 120
is_activebooleanfalse — the option is turned off and not offered.
is_defaultbooleanThe option is preselected: the storefront and the POS check it at once, and the server fills a required group left empty with it.
adds_ingredientsboolean or nullWhether this option changes the composition; null — as the group (adds_ingredients).
recipe_per_variantbooleanConsumption depends on the dish: no general composition, the amount is set by the recipe of each variant (option_recipes); without it the option is not offered on that variant.
nutritionobject or nullNutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.
Fields · 4
kcalintegerEnergy, kcal.
- Minimum:
- 0
- Maximum:
- 1000000
protein_mgintegerProtein, mg.
- Minimum:
- 0
- Maximum:
- 100000000
fat_mgintegerFat, mg.
- Minimum:
- 0
- Maximum:
- 100000000
carbs_mgintegerCarbohydrates, mg.
- Minimum:
- 0
- Maximum:
- 100000000
recipearray of objectGeneral composition of the option — what it consumes in any dish: ingredients and preps with their amount. Empty for a per-dish option. On write, the whole list, an empty one clears it; without the field the composition is left as it is.
- Max items:
- 100
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste: in the composition but not consumed.
- Max length:
- 32
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
min_selectintegerHow many options the customer must choose: 0 — the group is optional. A product can set its own rule (selection_rule).
- Minimum:
- 0
- Maximum:
- 99
max_selectinteger or nullHow many options can be chosen in total, repeats included; null — no limit.
- Minimum:
- 1
- Maximum:
- 99
is_activebooleanfalse — the group is turned off and not offered on products.
adds_ingredientsbooleanWhether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
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 ModifierGroup
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
consent_requiredConsent to the consequences is required - 409
external_id_archivedThe record with this external ID is archived - 409
external_id_in_useThe external ID is taken - 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 PATCH "https://api.saleya.app/v1/modifier-groups/{group}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"options": [
{
"id": 0,
"external_id": "string",
"name": {
"key": "string"
},
"price_delta": 0,
"max_quantity": 1,
"duration_minutes": 5,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 1,
"is_active": true,
"adds_ingredients": true,
"external_id": "string"
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Archive a modifier group
delete/modifier-groups/{group}
Scope: catalog:write
Parameters
Path
groupintegerrequiredID of the modifier group.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 1
modifier_group_archivestringArchiving the group removes it from products, breaks the selection in customer carts and removes its options from open draft orders.
- Min length:
- 64
- Max length:
- 64
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"
Responses
204Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
No body
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
consent_requiredConsent to the consequences is required - 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 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 DELETE "https://api.saleya.app/v1/modifier-groups/{group}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Get a modifier group by external ID
get/modifier-groups/by-external-id/{external_id}
Scope: catalog:read
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns ModifierGroup
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/modifier-groups/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Create or update a modifier group by external ID
patch/modifier-groups/by-external-id/{external_id}
Scope: catalog:write
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 1
modifier_product_minimumstringProducts with their own selection rule get a minimum equal to the number of enabled options of the group; otherwise they could not be bought.
- Min length:
- 64
- Max length:
- 64
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-MatchstringETag of the record from the last read. Required when a record with this external ID exists (otherwise 428) and must be absent when it does not.
- Example:
"7"
If-None-Matchstring* — create only: if a record with this external ID already exists, the request gets 412.
- Values:
*
Request body application/json
optionsarray of objectOptions in display order. On write, the whole set: a row finds its option by id or external_id, the found one gets the fields sent, a row without an option is new and carries name; an option missing from the set is archived and removed from open draft orders.
- Min items:
- 1
- Max items:
- 100
- No repeats
Fields · 12
idintegerID of the record, unique among records of its kind in the store.
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
price_deltaintegerSurcharge on the item price per portion of the option, an integer in minor units of the store currency; negative — a discount. A product can set its own surcharge by variant.
- Minimum:
- -100000000
- Maximum:
- 100000000
max_quantityinteger or nullHow many times the option can be taken in one item; null — no own limit, only the group max_select applies.
- Minimum:
- 1
- Maximum:
- 99
duration_minutesinteger or nullHow many minutes the option adds to a bookable service, a multiple of 5; null — none. Has no effect on other kinds of items.
- Minimum:
- 5
- Maximum:
- 120
is_activebooleanfalse — the option is turned off and not offered.
is_defaultbooleanThe option is preselected: the storefront and the POS check it at once, and the server fills a required group left empty with it.
adds_ingredientsboolean or nullWhether this option changes the composition; null — as the group (adds_ingredients).
recipe_per_variantbooleanConsumption depends on the dish: no general composition, the amount is set by the recipe of each variant (option_recipes); without it the option is not offered on that variant.
nutritionobject or nullNutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.
Fields · 4
kcalintegerEnergy, kcal.
- Minimum:
- 0
- Maximum:
- 1000000
protein_mgintegerProtein, mg.
- Minimum:
- 0
- Maximum:
- 100000000
fat_mgintegerFat, mg.
- Minimum:
- 0
- Maximum:
- 100000000
carbs_mgintegerCarbohydrates, mg.
- Minimum:
- 0
- Maximum:
- 100000000
recipearray of objectGeneral composition of the option — what it consumes in any dish: ingredients and preps with their amount. Empty for a per-dish option. On write, the whole list, an empty one clears it; without the field the composition is left as it is.
- Max items:
- 100
Fields · 2
variant_idintegerrequiredID of the product variant.
quantitystring or nullrequiredComponent amount for one use of the option, a decimal string in the unit of the component; null — to taste: in the composition but not consumed.
- Max length:
- 32
namemap of string or nullName by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.
- Max length:
- 255
min_selectintegerHow many options the customer must choose: 0 — the group is optional. A product can set its own rule (selection_rule).
- Minimum:
- 0
- Maximum:
- 99
max_selectinteger or nullHow many options can be chosen in total, repeats included; null — no limit.
- Minimum:
- 1
- Maximum:
- 99
is_activebooleanfalse — the group is turned off and not offered on products.
adds_ingredientsbooleanWhether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).
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 ModifierGroup
201Created
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"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns ModifierGroup
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
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
consent_requiredConsent to the consequences is required - 409
external_id_archivedThe record with this external ID is archived - 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 409
record_limit_reachedThe record limit is reached - 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 PATCH "https://api.saleya.app/v1/modifier-groups/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"options": [
{
"id": 0,
"external_id": "string",
"name": {
"key": "string"
},
"price_delta": 0,
"max_quantity": 1,
"duration_minutes": 5,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 1,
"is_active": true,
"adds_ingredients": true
}{
"id": 0,
"external_id": "string",
"version": 0,
"name": {
"key": "string"
},
"min_select": 0,
"max_select": 0,
"is_active": true,
"adds_ingredients": true,
"options": [
{
"id": 0,
"external_id": "string",
"name": {},
"price_delta": 0,
"max_quantity": 0,
"duration_minutes": 0,
"is_active": true,
"is_default": true,
"adds_ingredients": true,
"recipe_per_variant": true,
"nutrition": {
"kcal": 0,
"protein_mg": 0,
"fat_mg": 0,
"carbs_mg": 0
},
"recipe": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}