--- title: "Fetch an item" method: GET path: "/v1/items/{item_id}" tags: ["Items"] --- # Fetch an item `GET /v1/items/{item_id}` Fetch an item **Required scope: `business/catalogue:read`** **Deprecated alias:** `business/products:read` (still accepted, will be removed in a future release) ## Path parameters - `item_id` string, required — The unique identifier of the item. ## Query parameters - `expand` ExpandableItem[], nullable — Specifies which related entities to inflate in the response. Repeat the parameter to expand multiple entities, e.g. `?expand=brand&expand=category`. By default, related entities are returned only as identifiers (e.g. `brand_id`, `category_id`). ## Response `200` 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. - `is_taxable` boolean, required — Whether the item has taxes applied to it. - `taxes` ItemTax[] — The taxes applied to the item. - `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. - `barcode` string, nullable, required — The barcode of the variant. - `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_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-style modifier and product-style modifier. A note-style modifier attaches a text instruction, such as "medium-rare"; where as a product-style modifier attaches an additional variant to the item that may or may not impact the price. - `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 variant (`variant_id`). - `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 variant linked to this modifier. Populated only when `type` is `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. Only populated when `price_overrides` is requested via the `expand` query parameter. - `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. - `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-style modifier and product-style modifier. A note-style modifier attaches a text instruction, such as "medium-rare"; where as a product-style modifier attaches an additional variant to the item that may or may not impact the price. - `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 variant (`variant_id`). - `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 variant linked to this modifier. Populated only when `type` is `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. Only populated when `price_overrides` is requested via the `expand` query parameter. - `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. - `is_taxable` boolean, required — Whether the item has taxes applied to it. - `taxes` ItemTax[] — The taxes applied to the item. - `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. - `barcode` string, nullable, required — The barcode of the variant. - `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_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-style modifier and product-style modifier. A note-style modifier attaches a text instruction, such as "medium-rare"; where as a product-style modifier attaches an additional variant to the item that may or may not impact the price. - `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 variant (`variant_id`). - `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 variant linked to this modifier. Populated only when `type` is `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. Only populated when `price_overrides` is requested via the `expand` query parameter. - `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. - `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-style modifier and product-style modifier. A note-style modifier attaches a text instruction, such as "medium-rare"; where as a product-style modifier attaches an additional variant to the item that may or may not impact the price. - `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 variant (`variant_id`). - `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 variant linked to this modifier. Populated only when `type` is `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. Only populated when `price_overrides` is requested via the `expand` query parameter. - `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 - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `429` — Too Many Requests --- [API](https://skmtc.net/yoco/apis/yoco-api.md) · [All operations](https://skmtc.net/yoco/apis/yoco-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yoco/yoco-api/revisions/1ee03e82bc45/schema)