Modifier groups

Choices for an item: sauces, extras, portion size. The group sets the selection bounds, options set surcharge and composition.

Loading the search index…

Modifier groups

Objects

ModifierGroup

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • external_idstring or nullrequired

    External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

  • versionintegerrequired

    Version of the record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • namemap of stringrequired

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

  • min_selectintegerrequired

    How many options the customer must choose: 0 — the group is optional. A product can set its own rule (selection_rule).

  • max_selectinteger or nullrequired

    How many options can be chosen in total, repeats included; null — no limit.

  • is_activebooleanrequired

    false — the group is turned off and not offered on products.

  • adds_ingredientsbooleanrequired

    Whether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).

  • optionsarray of objectrequired

    Options 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
    • idintegerrequired

      ID of the record, unique among records of its kind in the store.

    • external_idstring or nullrequired

      External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

    • nameobjectrequired

      Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    • price_deltaintegerrequired

      Surcharge 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 nullrequired

      How many times the option can be taken in one item; null — no own limit, only the group max_select applies.

    • duration_minutesinteger or nullrequired

      How many minutes the option adds to a bookable service, a multiple of 5; null — none. Has no effect on other kinds of items.

    • is_activebooleanrequired

      false — the option is turned off and not offered.

    • is_defaultbooleanrequired

      The 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 nullrequired

      Whether this option changes the composition; null — as the group (adds_ingredients).

    • recipe_per_variantbooleanrequired

      Consumption 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 nullrequired

      Nutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.

      Fields · 4
      • kcalintegerrequired

        Energy, kcal.

      • protein_mgintegerrequired

        Protein, mg.

      • fat_mgintegerrequired

        Fat, mg.

      • carbs_mgintegerrequired

        Carbohydrates, mg.

    • recipearray of objectrequired

      General 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_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

  • deleted_atstring (date-time) or nullrequired

    When 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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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

  • dataarray of ModifierGrouprequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/modifier-groups" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-Keystring

    Unique 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 nullrequired

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • min_selectinteger

    How 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 null

    How many options can be chosen in total, repeats included; null — no limit.

    Minimum:
    1
    Maximum:
    99
  • is_activeboolean

    false — the group is turned off and not offered on products.

  • adds_ingredientsboolean

    Whether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).

  • optionsarray of objectrequired

    Options 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 null

      External 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 null

      Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

      Max length:
      255
    • price_deltainteger

      Surcharge 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 null

      How 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 null

      How 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_activeboolean

      false — the option is turned off and not offered.

    • is_defaultboolean

      The 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 null

      Whether this option changes the composition; null — as the group (adds_ingredients).

    • recipe_per_variantboolean

      Consumption 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 null

      Nutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.

      Fields · 4
      • kcalinteger

        Energy, kcal.

        Minimum:
        0
        Maximum:
        1000000
      • protein_mginteger

        Protein, mg.

        Minimum:
        0
        Maximum:
        100000000
      • fat_mginteger

        Fat, mg.

        Minimum:
        0
        Maximum:
        100000000
      • carbs_mginteger

        Carbohydrates, mg.

        Minimum:
        0
        Maximum:
        100000000
    • recipearray of object

      General 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_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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 null

    External 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl -X POST "https://api.saleya.app/v1/modifier-groups" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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"
}
Example response · 201
{
  "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

  • groupintegerrequired

    ID of the modifier group.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/modifier-groups/{group}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • groupintegerrequired

    ID of the modifier group.

Query

  • consentobject

    Consents 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_minimumstring

      Products 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-Keystring

    Unique 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-Matchstringrequired

    ETag 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 object

    Options 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
    • idinteger

      ID of the record, unique among records of its kind in the store.

    • external_idstring or null

      External 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 null

      Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

      Max length:
      255
    • price_deltainteger

      Surcharge 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 null

      How 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 null

      How 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_activeboolean

      false — the option is turned off and not offered.

    • is_defaultboolean

      The 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 null

      Whether this option changes the composition; null — as the group (adds_ingredients).

    • recipe_per_variantboolean

      Consumption 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 null

      Nutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.

      Fields · 4
      • kcalinteger

        Energy, kcal.

        Minimum:
        0
        Maximum:
        1000000
      • protein_mginteger

        Protein, mg.

        Minimum:
        0
        Maximum:
        100000000
      • fat_mginteger

        Fat, mg.

        Minimum:
        0
        Maximum:
        100000000
      • carbs_mginteger

        Carbohydrates, mg.

        Minimum:
        0
        Maximum:
        100000000
    • recipearray of object

      General 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_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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 null

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • min_selectinteger

    How 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 null

    How many options can be chosen in total, repeats included; null — no limit.

    Minimum:
    1
    Maximum:
    99
  • is_activeboolean

    false — the group is turned off and not offered on products.

  • adds_ingredientsboolean

    Whether the group options change the dish composition; with true, an option without its own composition makes the item composition unknown (allergens).

  • external_idstring or null

    External 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
}
Example response · 200
{
  "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

  • groupintegerrequired

    ID of the modifier group.

Query

  • consentobject

    Consents 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_archivestring

      Archiving 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-Keystring

    Unique 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-Matchstringrequired

    ETag 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-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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_idstringrequired

    External ID: the ID of the record in your system.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/modifier-groups/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_idstringrequired

    External ID: the ID of the record in your system.

Query

  • consentobject

    Consents 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_minimumstring

      Products 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-Keystring

    Unique 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-Matchstring

    ETag 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 object

    Options 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
    • idinteger

      ID of the record, unique among records of its kind in the store.

    • external_idstring or null

      External 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 null

      Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

      Max length:
      255
    • price_deltainteger

      Surcharge 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 null

      How 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 null

      How 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_activeboolean

      false — the option is turned off and not offered.

    • is_defaultboolean

      The 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 null

      Whether this option changes the composition; null — as the group (adds_ingredients).

    • recipe_per_variantboolean

      Consumption 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 null

      Nutrition of one use of the option declared by the store: all four numbers or null — then the option composition computes it.

      Fields · 4
      • kcalinteger

        Energy, kcal.

        Minimum:
        0
        Maximum:
        1000000
      • protein_mginteger

        Protein, mg.

        Minimum:
        0
        Maximum:
        100000000
      • fat_mginteger

        Fat, mg.

        Minimum:
        0
        Maximum:
        100000000
      • carbs_mginteger

        Carbohydrates, mg.

        Minimum:
        0
        Maximum:
        100000000
    • recipearray of object

      General 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_idintegerrequired

        ID of the product variant.

      • quantitystring or nullrequired

        Component 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 null

    Name by language: an object of the filled languages, for example {"es": "Café", "en": "Coffee"}.

    Max length:
    255
  • min_selectinteger

    How 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 null

    How many options can be chosen in total, repeats included; null — no limit.

    Minimum:
    1
    Maximum:
    99
  • is_activeboolean

    false — the group is turned off and not offered on products.

  • adds_ingredientsboolean

    Whether 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-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns ModifierGroup

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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
}
Example response · 200
{
  "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"
}