---
title: "Create an item"
method: POST
path: "/v1/items/"
tags: ["Items"]
---

# Create an item

`POST /v1/items/`

## Request

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

Create an item

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

## Request body

- CreateItemRequest: `CreateItemRequest` carries a new item. An optional field left out of the request is stored empty.
  - `name` string, required: The name of the item.
  - `description` string, nullable: A description of the item.
  - `default_price` NonNegativeMoney, required: `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.
  - `default_barcode` string, nullable: The barcode of the item. A variant without a barcode of its own reports this value as its `barcode`.
  - `default_cost_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.
  - `default_duration` integer, nullable: The duration of the service, in minutes.
  - `type` 'product' | 'service', required
  - `stock_tracking` 'item' | 'none' | 'variant': `StockTracking` is whether the Yoco Point of Sale (POS) app tracks stock for an item. `none` doesn't track stock. `item` keeps one count shared by all of the item's variants. `variant` keeps a separate count for each variant.
  - `category_id` string, nullable: The unique identifier of the category the item belongs to.
  - `brand_id` string, nullable: The unique identifier of the brand the item belongs to. Only a `product` can belong to a brand, so a `service` may leave it out.
  - `image_id` string, nullable: The unique identifier of the item's image: the `id` of a media item uploaded with `POST /v1/media/`.
  - `tax_ids` string[], nullable: The unique identifiers of the taxes to apply to the item. `null` or `[]` removes the item's own taxes, so the business's default tax applies. To charge no tax, send the id of a tax from `GET /v1/taxes` whose `percentage` is `0`, such as No Tax if the business has one.
  - `options` CreateItemOptionRequest[], nullable: The options the item varies by, e.g. `Size`. An item with options needs one variant for every combination of their values. Send `[]` or `null` for an item without options.
    - `name` string, required: The name of the option, e.g. `Size`.
    - `values` CreateItemOptionValueRequest[], required: The values the option can take, e.g. `Small` and `Large`.
      - `name` string, required: The name of the item option value.
    - `id` unknown
  - `variants` CreateItemVariantRequest[], nullable: The purchasable variants of the item, one for every combination of the item's `options` values. Send `[]` or `null` for an item without variants.
    - `sku` string, nullable: The SKU (stock keeping unit) of the variant. Used only when the item tracks stock per variant. Otherwise every variant uses the item's SKU and this value is ignored. When it is used, `null` or an empty string keeps an existing variant's SKU, and a new variant gets a SKU generated from the item's SKU and its option values.
    - `barcode` string, nullable: The barcode of the variant.
    - `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.
    - `cost_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.
    - `duration` integer, nullable: The duration of the service variant, in minutes.
    - `is_enabled` boolean: Whether the variant is available as a purchase option in the Yoco Point of Sale (POS) app.
    - `selected_options` CreateSelectedOptionRequest[], nullable: The option value selected for each of the item's `options`, e.g. `Size` of `Small`. Exactly one value is required per option the item declares. Any order is accepted, and the response lists them in the order of the item's `options`. Send `[]` or `null` for an item without options.
      - `name` string, required: The name of the item option.
      - `value` string, required: The value of the option for this variant.
    - `modifier_groups` AttachItemModifierGroupRequest[], nullable: Must be `[]` or `null`: modifier groups attach to the item, through its `modifier_groups`, and apply to every variant.
      - `id` string, required: The unique identifier of the modifier group.
      - `ordinal` integer, required: The position of the group among the item's modifier groups. Lower values appear first. The response returns the position Yoco stores, which keeps the order but can differ from the value sent.
    - `location_availability` CreateItemLocationAvailabilityRequest: `CreateItemLocationAvailabilityRequest` carries the location availability of a new item or variant. A location list left out of the request is stored empty.
      - `is_available_at_all_locations` boolean, required: Whether the item or variant is available at every location. When `true`, `excluded_location_ids` lists the exceptions. When `false`, `included_location_ids` lists the only locations that sell it.
      - `included_location_ids` string[]: The unique identifiers of the only locations that sell the item or variant. Must be empty when `is_available_at_all_locations` is `true`.
      - `excluded_location_ids` string[]: The unique identifiers of the locations that do not sell the item or variant. Must be empty when `is_available_at_all_locations` is `false`.
    - `id` unknown
  - `price_overrides` CreateItemPriceOverrideRequest[], nullable: The prices the item charges at specific locations, in place of its `default_price`. A location may have only one price override. Send `[]` or `null` to remove every price override from the item.
    - `price` NonNegativeMoney, required: `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.
    - `location_ids` string[], required: The unique identifiers of the locations that charge this price.
    - `id` unknown
  - `location_availability` CreateItemLocationAvailabilityRequest: `CreateItemLocationAvailabilityRequest` carries the location availability of a new item or variant. A location list left out of the request is stored empty.
    - `is_available_at_all_locations` boolean, required: Whether the item or variant is available at every location. When `true`, `excluded_location_ids` lists the exceptions. When `false`, `included_location_ids` lists the only locations that sell it.
    - `included_location_ids` string[]: The unique identifiers of the only locations that sell the item or variant. Must be empty when `is_available_at_all_locations` is `true`.
    - `excluded_location_ids` string[]: The unique identifiers of the locations that do not sell the item or variant. Must be empty when `is_available_at_all_locations` is `false`.
  - `modifier_groups` AttachItemModifierGroupRequest[], nullable: The modifier groups attached to the item, which apply to every variant. Each group may be attached once, and each `ordinal` used once. Send `[]` or `null` to detach every group.
    - `id` string, required: The unique identifier of the modifier group.
    - `ordinal` integer, required: The position of the group among the item's modifier groups. Lower values appear first. The response returns the position Yoco stores, which keeps the order but can differ from the value sent.

## Response `201`

Successful Response

- union
  - ProductItem
    - `id` string, required: The unique identifier of the item.
    - `name` string, required: The name of the item.
    - `description` string, nullable, required: A description of the item.
    - `default_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.
    - `default_barcode` string, nullable, required: The barcode set on the item itself. Variants without a barcode of their own report this value as their `barcode`.
    - `default_cost_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.
    - `default_duration` integer, nullable, required: The duration of the service, in minutes.
    - `is_taxable` boolean, required: Whether tax is charged when the item is sold. An item with no taxes of its own is charged the business's default tax. `false` when every tax that applies has a rate of 0%, so a zero-rated item and an exempt item both report `false`.
    - `taxes` ItemTax[]: The item's own taxes, set with `tax_ids`. Empty when the business's default tax applies to the item.
      - `id` string, required: The unique identifier of the tax.
      - `name` string, required: A human-readable name for the tax.
      - `type` 'additive' | 'inclusive', required: `TaxType` can be either `additive` or `inclusive` and affects how tax is calculated. For `additive` tax, the tax is calculated on top of the price. For example, an item which costs R100.00 with a 15% additive tax has a total cost to the buyer of R115.00 (R100.00 * 1.15). The tax amount is therefore R115.00 - R100.00 = R15.00. For `inclusive` tax, the tax is included in the price. For example, an item which costs R115.00 with a 15% inclusive tax has a total cost to the buyer of R115.00. The tax amount is R15.00 (R115.00 * 15/115) whilst the taxable amount is R100 (R115.00 - R15.00).
      - `percentage` string, required: The tax rate to apply. For example, `15.00` corresponds to a tax rate of `15%`.
    - `images` Media[]: A list of images associated with the item.
      - `id` string, required: The unique identifier of the media.
      - `type` 'image', required
      - `mime_type` string, required: The mime type indicates the format of the media.
      - `url` string, required: The URL of the media file.
      - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
    - `category_id` string, nullable, required: The unique identifier of the category the item belongs to.
    - `category` ItemCategory
      - `id` string, required: The unique identifier of the category.
      - `name` string, required: The name of the category.
      - `description` string, nullable, required: A description of the category.
      - `image` Media, required
        - `id` string, required: The unique identifier of the media.
        - `type` 'image', required
        - `mime_type` string, required: The mime type indicates the format of the media.
        - `url` string, required: The URL of the media file.
        - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
        - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
      - `created_at` string, date-time, required: The category creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the category was last modified in ISO 8601 format.
      - `parent_category` ParentItemCategory, required
        - `id` string, required: The unique identifier of the category.
        - `name` string, required: The name of the category.
        - `description` string, nullable, required: A description of the category.
        - `image` Media, required
          - `id` string, required: The unique identifier of the media.
          - `type` 'image', required
          - `mime_type` string, required: The mime type indicates the format of the media.
          - `url` string, required: The URL of the media file.
          - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
          - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
        - `created_at` string, date-time, required: The category creation date and time in ISO 8601 format.
        - `updated_at` string, date-time, nullable, required: The date and time the category was last modified in ISO 8601 format.
    - `options` ItemOption[]: The item options associated with the item.
      - `id` string, required: The unique identifier of the item option.
      - `name` string, required: The name of the item option.
      - `values` ItemOptionValue[]: A list of values that form the item option.
        - `name` string, required: The name of the item option value.
      - `created_at` string, date-time, required: The item option creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the item option was last modified in ISO 8601 format.
    - `has_multiple_variants` boolean, required: Whether the item has more than one variant.
    - `variants` ItemVariant[]: The variants of the item.
      - `id` string, required: The unique identifier of the variant.
      - `sku` string, nullable, required: The SKU (stock keeping unit) of the variant. When the item does not track stock per variant, every variant shows the item's SKU.
      - `barcode` string, nullable, required: The barcode of the variant. If the variant has no barcode, this field shows the `default_barcode` of the item. All variants that have no barcode show the same value.
      - `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.
      - `cost_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.
      - `duration` integer, nullable, required: The duration of the service variant, in minutes.
      - `is_enabled` boolean, required: Whether the variant is available as a purchase option in the Yoco Point of Sale (POS) app.
      - `selected_options` SelectedOption[]: The option values selected for this variant, ordered to match the item's `options`. Each entry pairs an option group name (e.g. `Size`) with the value chosen for this variant (e.g. `Small`).
        - `name` string, required: The name of the item option.
        - `value` string, required: The value of the option for this variant.
      - `modifier_groups` ItemModifierGroup[]: The modifier groups attached specifically to this variant.
        - `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.
        - `ordinal` integer, required: The display ordering of the group on its parent item or variant. Lower values appear first.
        - `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 variant creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the variant was last modified in ISO 8601 format.
      - `price_overrides` ItemPriceOverride[], nullable: The location-specific price overrides for this variant. Present when `price_overrides` is requested via the `expand` query parameter, and always on create and update responses.
        - `id` string, required: The unique identifier of the price override.
        - `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.
        - `location_ids` string[], required: The location IDs this price override applies to.
      - `location_availability` ItemLocationAvailability
        - `is_available_at_all_locations` boolean, required: Whether the item is available at all locations by default.
        - `included_location_ids` string[]: Location IDs where the item is explicitly available. Populated when `is_available_at_all_locations` is `false`; empty otherwise.
        - `excluded_location_ids` string[]: Location IDs where the item is explicitly unavailable. Populated when `is_available_at_all_locations` is `true`; empty otherwise.
    - `stock_tracking` 'item' | 'none' | 'variant', required: `StockTracking` is whether the Yoco Point of Sale (POS) app tracks stock for an item. `none` doesn't track stock. `item` keeps one count shared by all of the item's variants. `variant` keeps a separate count for each variant.
    - `modifier_groups` ItemModifierGroup[]: The modifier groups attached to this item.
      - `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.
      - `ordinal` integer, required: The display ordering of the group on its parent item or variant. Lower values appear first.
      - `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 item creation date and time in ISO 8601 format.
    - `updated_at` string, date-time, nullable, required: The date and time the item was last modified in ISO 8601 format.
    - `location_availability` ItemLocationAvailability
      - `is_available_at_all_locations` boolean, required: Whether the item is available at all locations by default.
      - `included_location_ids` string[]: Location IDs where the item is explicitly available. Populated when `is_available_at_all_locations` is `false`; empty otherwise.
      - `excluded_location_ids` string[]: Location IDs where the item is explicitly unavailable. Populated when `is_available_at_all_locations` is `true`; empty otherwise.
    - `price_overrides` ItemPriceOverride[], nullable: The location-specific price overrides for this item's default price. Present when `price_overrides` is requested via the `expand` query parameter, and always on create and update responses.
      - `id` string, required: The unique identifier of the price override.
      - `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.
      - `location_ids` string[], required: The location IDs this price override applies to.
    - `type` 'product', required: Discriminator value identifying this item as a physical product.
    - `brand_id` string, nullable, required: The unique identifier of the brand the product belongs to.
    - `brand` ItemBrand
      - `id` string, required: The unique identifier of the brand.
      - `name` string, required: The name of the brand.
      - `description` string, nullable, required: A description of the brand.
      - `image` Media, required
        - `id` string, required: The unique identifier of the media.
        - `type` 'image', required
        - `mime_type` string, required: The mime type indicates the format of the media.
        - `url` string, required: The URL of the media file.
        - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
        - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
      - `created_at` string, date-time, required: The brand creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the brand was last modified in ISO 8601 format.
  - ServiceItem
    - `id` string, required: The unique identifier of the item.
    - `name` string, required: The name of the item.
    - `description` string, nullable, required: A description of the item.
    - `default_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.
    - `default_barcode` string, nullable, required: The barcode set on the item itself. Variants without a barcode of their own report this value as their `barcode`.
    - `default_cost_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.
    - `default_duration` integer, nullable, required: The duration of the service, in minutes.
    - `is_taxable` boolean, required: Whether tax is charged when the item is sold. An item with no taxes of its own is charged the business's default tax. `false` when every tax that applies has a rate of 0%, so a zero-rated item and an exempt item both report `false`.
    - `taxes` ItemTax[]: The item's own taxes, set with `tax_ids`. Empty when the business's default tax applies to the item.
      - `id` string, required: The unique identifier of the tax.
      - `name` string, required: A human-readable name for the tax.
      - `type` 'additive' | 'inclusive', required: `TaxType` can be either `additive` or `inclusive` and affects how tax is calculated. For `additive` tax, the tax is calculated on top of the price. For example, an item which costs R100.00 with a 15% additive tax has a total cost to the buyer of R115.00 (R100.00 * 1.15). The tax amount is therefore R115.00 - R100.00 = R15.00. For `inclusive` tax, the tax is included in the price. For example, an item which costs R115.00 with a 15% inclusive tax has a total cost to the buyer of R115.00. The tax amount is R15.00 (R115.00 * 15/115) whilst the taxable amount is R100 (R115.00 - R15.00).
      - `percentage` string, required: The tax rate to apply. For example, `15.00` corresponds to a tax rate of `15%`.
    - `images` Media[]: A list of images associated with the item.
      - `id` string, required: The unique identifier of the media.
      - `type` 'image', required
      - `mime_type` string, required: The mime type indicates the format of the media.
      - `url` string, required: The URL of the media file.
      - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
    - `category_id` string, nullable, required: The unique identifier of the category the item belongs to.
    - `category` ItemCategory
      - `id` string, required: The unique identifier of the category.
      - `name` string, required: The name of the category.
      - `description` string, nullable, required: A description of the category.
      - `image` Media, required
        - `id` string, required: The unique identifier of the media.
        - `type` 'image', required
        - `mime_type` string, required: The mime type indicates the format of the media.
        - `url` string, required: The URL of the media file.
        - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
        - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
      - `created_at` string, date-time, required: The category creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the category was last modified in ISO 8601 format.
      - `parent_category` ParentItemCategory, required
        - `id` string, required: The unique identifier of the category.
        - `name` string, required: The name of the category.
        - `description` string, nullable, required: A description of the category.
        - `image` Media, required
          - `id` string, required: The unique identifier of the media.
          - `type` 'image', required
          - `mime_type` string, required: The mime type indicates the format of the media.
          - `url` string, required: The URL of the media file.
          - `created_at` string, date-time, required: The media creation date and time in ISO 8601 format.
          - `updated_at` string, date-time, nullable, required: The date and time the media was last modified in ISO 8601 format.
        - `created_at` string, date-time, required: The category creation date and time in ISO 8601 format.
        - `updated_at` string, date-time, nullable, required: The date and time the category was last modified in ISO 8601 format.
    - `options` ItemOption[]: The item options associated with the item.
      - `id` string, required: The unique identifier of the item option.
      - `name` string, required: The name of the item option.
      - `values` ItemOptionValue[]: A list of values that form the item option.
        - `name` string, required: The name of the item option value.
      - `created_at` string, date-time, required: The item option creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the item option was last modified in ISO 8601 format.
    - `has_multiple_variants` boolean, required: Whether the item has more than one variant.
    - `variants` ItemVariant[]: The variants of the item.
      - `id` string, required: The unique identifier of the variant.
      - `sku` string, nullable, required: The SKU (stock keeping unit) of the variant. When the item does not track stock per variant, every variant shows the item's SKU.
      - `barcode` string, nullable, required: The barcode of the variant. If the variant has no barcode, this field shows the `default_barcode` of the item. All variants that have no barcode show the same value.
      - `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.
      - `cost_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.
      - `duration` integer, nullable, required: The duration of the service variant, in minutes.
      - `is_enabled` boolean, required: Whether the variant is available as a purchase option in the Yoco Point of Sale (POS) app.
      - `selected_options` SelectedOption[]: The option values selected for this variant, ordered to match the item's `options`. Each entry pairs an option group name (e.g. `Size`) with the value chosen for this variant (e.g. `Small`).
        - `name` string, required: The name of the item option.
        - `value` string, required: The value of the option for this variant.
      - `modifier_groups` ItemModifierGroup[]: The modifier groups attached specifically to this variant.
        - `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.
        - `ordinal` integer, required: The display ordering of the group on its parent item or variant. Lower values appear first.
        - `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 variant creation date and time in ISO 8601 format.
      - `updated_at` string, date-time, nullable, required: The date and time the variant was last modified in ISO 8601 format.
      - `price_overrides` ItemPriceOverride[], nullable: The location-specific price overrides for this variant. Present when `price_overrides` is requested via the `expand` query parameter, and always on create and update responses.
        - `id` string, required: The unique identifier of the price override.
        - `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.
        - `location_ids` string[], required: The location IDs this price override applies to.
      - `location_availability` ItemLocationAvailability
        - `is_available_at_all_locations` boolean, required: Whether the item is available at all locations by default.
        - `included_location_ids` string[]: Location IDs where the item is explicitly available. Populated when `is_available_at_all_locations` is `false`; empty otherwise.
        - `excluded_location_ids` string[]: Location IDs where the item is explicitly unavailable. Populated when `is_available_at_all_locations` is `true`; empty otherwise.
    - `stock_tracking` 'item' | 'none' | 'variant', required: `StockTracking` is whether the Yoco Point of Sale (POS) app tracks stock for an item. `none` doesn't track stock. `item` keeps one count shared by all of the item's variants. `variant` keeps a separate count for each variant.
    - `modifier_groups` ItemModifierGroup[]: The modifier groups attached to this item.
      - `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.
      - `ordinal` integer, required: The display ordering of the group on its parent item or variant. Lower values appear first.
      - `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 item creation date and time in ISO 8601 format.
    - `updated_at` string, date-time, nullable, required: The date and time the item was last modified in ISO 8601 format.
    - `location_availability` ItemLocationAvailability
      - `is_available_at_all_locations` boolean, required: Whether the item is available at all locations by default.
      - `included_location_ids` string[]: Location IDs where the item is explicitly available. Populated when `is_available_at_all_locations` is `false`; empty otherwise.
      - `excluded_location_ids` string[]: Location IDs where the item is explicitly unavailable. Populated when `is_available_at_all_locations` is `true`; empty otherwise.
    - `price_overrides` ItemPriceOverride[], nullable: The location-specific price overrides for this item's default price. Present when `price_overrides` is requested via the `expand` query parameter, and always on create and update responses.
      - `id` string, required: The unique identifier of the price override.
      - `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.
      - `location_ids` string[], required: The location IDs this price override applies to.
    - `type` 'service', required: Discriminator value identifying this item as a service.

## Other responses

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

## Changes

- **2026-10-22** `f961bea3a9a4`: 4 breaking, 5 info
  - the `default_duration` request property format changed from `int32` to no format
  - the `default_duration/anyOf[subschema #1]/` request property format changed from no format to `int32`
  - the `variants/anyOf[subschema #1]/items/duration` request property format changed from `int32` to no format
  - the `variants/anyOf[subschema #1]/items/duration/anyOf[subschema #1]/` request property format changed from no format to `int32`
  - …5 more
- **2026-10-20** `ed6f9d39b4eb`: 1 info
  - added the new optional request property `variants/anyOf[subschema #1]/items/location_availability`
- **2026-10-20** `f02252438dd3`: 6 info
  - added the new optional request property `default_cost_price`
  - added the new optional request property `variants/anyOf[subschema #1]/items/cost_price`
  - added the required property `oneOf[subschema #1: ProductItem]/default_cost_price` to the response with the `201` status
  - added the required property `oneOf[subschema #1: ProductItem]/variants/items/cost_price` to the response with the `201` status
  - …2 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/yoco/apis/yoco-api/changes/v1/items/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)