---
title: "Create a modifier group"
method: POST
path: "/v1/modifier_groups/"
tags: ["Modifier Groups"]
---

# Create a modifier group

`POST /v1/modifier_groups/`

## Request

- Base URL: `https://api.yoco.com`
- URL: `https://api.yoco.com/v1/modifier_groups/`
- Auth: HTTP bearer

Create a modifier group

**Required scopes: `business/catalogue:read`, `business/catalogue:write`**

## Request body

- CreateModifierGroupRequest: `CreateModifierGroupRequest` carries a new modifier group. An optional field left out of the request is stored empty.
  - `name` string, required: The name of the modifier group. It must be unique among the business's modifier groups.
  - `min_selections` integer, required: The minimum number of modifiers that must be selected from the group. A value of `0` means the group is optional.
  - `max_selections` integer, nullable: The maximum number of modifiers that may be selected from the group. A value of `null` means there is no maximum.
  - `modifiers` CreateModifierRequest[], required: The complete set of modifiers in the group. A group holds at least one modifier.
    - `name` string, required: The display name of the modifier.
    - `pricing_strategy` 'fixed_price' | 'free' | 'product', required: `PricingStrategy` determines how the price of a modifier is calculated when applied to an item. - `free`: the modifier does not change the price of the item. - `fixed_price`: the modifier applies the price set in `fixed_price`. - `product`: the modifier inherits the price of its linked item variant (`variant_id`). Available only on `product` modifiers.
    - `fixed_price` NonNegativeMoney: `NonNegativeMoney` is a `Money` whose amount is not negative.
      - `amount` integer, required: The amount of money in the smallest denomination of the currency. For example, when the `currency` is `ZAR`, the `amount` is in cents.
      - `currency` string, required: The currency code in ISO 4217 format.
    - `is_selected_by_default` boolean, required: Whether the modifier is selected by default when its group is shown to the customer.
    - `ordinal` integer, required: The display ordering of the modifier within its group. Lower values appear first. Unique within the group.
    - `variant_id` string, nullable: The unique identifier of the item variant this modifier adds to the item, or `null` when none is linked. Required when `pricing_strategy` is `product`. On an update, `null` removes the link.
    - `id` unknown

## Response `201`

Successful Response

- ModifierGroup: A reusable collection of modifiers that share selection rules. Each group owns one or more `Modifier` options and defines `min_selections` and `max_selections` to constrain how many can be chosen at sale time. Groups exist independently of items and are reused across the catalogue — a single "Doneness" group can be attached to many products. When a group is attached to a product or variant for sale, the item-side view is `ItemModifierGroup`.
  - `id` string, required: The unique identifier of the modifier group.
  - `name` string, required: The name of the modifier group.
  - `min_selections` integer, required: The minimum number of modifiers that must be selected from the group. A value of `0` means the group is optional.
  - `max_selections` integer, nullable, required: The maximum number of modifiers that may be selected from the group. A value of `null` means there is no maximum.
  - `modifiers` Modifier[]: The modifiers that belong to this group.
    - `id` string, required: The unique identifier of the modifier.
    - `modifier_group_id` string, required: The unique identifier of the modifier group this modifier belongs to.
    - `type` 'note' | 'product', required: `ModifierType` distinguishes between a `note` modifier and a `product` modifier. A `note` modifier has no linked item variant, such as "medium-rare". A `product` modifier adds an item variant to the item, linked through `variant_id`. Both `note` and `product` modifiers may carry a charge, set by `pricing_strategy`.
    - `name` string, required: The display name of the modifier.
    - `pricing_strategy` 'fixed_price' | 'free' | 'product', required: `PricingStrategy` determines how the price of a modifier is calculated when applied to an item. - `free`: the modifier does not change the price of the item. - `fixed_price`: the modifier applies the price set in `fixed_price`. - `product`: the modifier inherits the price of its linked item variant (`variant_id`). Available only on `product` modifiers.
    - `fixed_price` Money, required: `Money` represents a monetary value denoted by both an amount and a currency. The `amount` is always going to be the smallest denomination of the given currency. As an example, when dealing with South African Rands (ZAR), the amount is in cents. eg: R150.45 is therefore represented by `Money(amount=15045, currency="ZAR")`.
      - `amount` integer, required: The amount of money in the smallest denomination of the currency. For example, when the `currency` is `ZAR`, the `amount` is in cents.
      - `currency` string, required: The currency code in ISO 4217 format.
    - `is_selected_by_default` boolean, required: Whether the modifier is selected by default when its group is shown to the customer.
    - `ordinal` integer, required: The display ordering of the modifier within its group. Lower values appear first.
    - `variant_id` string, nullable, required: The unique identifier of the item variant linked to this modifier, or `null` when none is linked. A linked modifier has the `type` `product`.
  - `created_at` string, date-time, required: The modifier group creation date and time in ISO 8601 format.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `429`: Too Many Requests

## Changes

- **2026-10-22** `f961bea3a9a4`: 1 info
  - added the new optional request property `modifiers/items/id`
- **2026-10-21** `8cec45c093ae`: 2 breaking
  - the `modifiers/items/variant_id/anyOf[subschema #1]/` request property's minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9:-]+$` to the request property `modifiers/items/variant_id/anyOf[subschema #1]/`
- **2026-10-15** `2505c2f21875`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/yoco/apis/yoco-api/changes/v1/modifier_groups/post.md)

---

[API](https://skmtc.dev/yoco/apis/yoco-api.md) - [All operations](https://skmtc.dev/yoco/apis/yoco-api/llms.txt) - [OpenAPI document](https://skmtc.dev/yoco/apis/yoco-api/revisions/daf9b9d86161?raw)