Items (item)

Auth

• GET is PUBLIC for item only when application_id is provided as a query param.
• POST / DELETE require authorization: either
  • Authorization: Bearer {{oauth_access_token}} (OAuth client_credentials token), or
  • mobstep-customer-token: {{customer_token}} (customer token)

Base URL

• {{base_path}}{{api_v3_path}}/item

Notes

• Friendly entity names are supported in URLs (example: /item).
• Legacy internal names (example: /apps_item) are still accepted for backward compatibility.

GET Query Parameters (supported by API v3)

• fields (required)
  • Comma-separated list of fields to include in the response.
  • If missing/empty: 400 invalid_request Parameter fields is required.
  • Example: fields=id,name,base_price,application_id
• locale (optional)
  • Supported values: primary (default), secondary.
  • When locale=secondary, the API may override some primary fields with their secondary-language values but you still request the base field names (do not request any *_secondary fields).
• application_id (required for public GET only)
  • Required for public GET (item is public when application_id exists).
  • When authorized, application_id is scoped from auth context and query param is ignored.
• sort (optional)
  • Format: sort=<field>,<ASC|DESC>
  • Example: sort=created,DESC
  • If field not allowed: 400 invalid_sort.
  • Default when not provided: created,DESC.
• range (optional; pagination)
  • Format: range=<offset>,<limit>
  • Example: range=0,50
  • Default when not provided: range=0,300.
  • If invalid: 400 invalid_range.
• search (optional; contains search)
  • Format: search=<field>,<value>
  • Multiple OR groups: separate by |
  • Example: search=name,cola|short_description,zero
• group (optional)
  • Format: group=<field>
  • Example: group=category_id
  • If field not allowed: 400 invalid_group.
• Filter by field value (optional)
  • You can pass any field name as a query parameter to filter results.
  • Values are comma-separated and applied as an IN condition.
  • Example: available=1 or category_id=10,12,15

Fields (item)

Field	Type	Required	Read-only	Default	Meaning / Description
id	integer	no	yes	-	The ID of the Item entity.
uuid	uuid	no	yes	-	The UUID of the Item entity.
iid	integer	no	no	-	The IID of the entity (legacy/internal identifier).
name	string	yes	no	-	Primary item name (default language).
short_description	string	no	no	-	Short item description (default language).
description	text_long	no	no	-	Full item description (default language).
item_image	image[]	no	no	-	Item images (multiple). In GET responses this is returned as processed image objects/URLs.
base_price	decimal	no	no	-	Base price of the item.
sale_price	decimal	no	no	-	Sale/discounted price of the item (if any).
rewards_catalog	boolean	no	no	false	Whether the item is part of rewards catalog.
loyalty_points	decimal	no	no	-	Loyalty points value associated with the item.
stock	integer	no	no	100000	Available stock quantity (used if tracking inventory logic depends on it).
category_id	entity_reference (apps_category)[]	no	no	-	Categories this item belongs to (multiple).
weight	integer	no	no	-	Item weight (used for delivery/pricing logic where applicable).
available	boolean	no	no	true	Whether the item is currently available for ordering.
quantity_step	decimal	no	no	1	Defines the increment step of the quantity (e.g. 1 for piece, 0.01 for grams/ml, etc.).
quantity_min	decimal	no	no	1	Defines the minimum allowed quantity for this item.
quantity_max	decimal	no	no	-	Defines the maximum allowed quantity for this item.
track_inventory	boolean	no	no	false	If enabled, stock is treated as finite and decremented/validated by inventory logic.
has_components	boolean	no	no	false	Enable BOM (bill of materials) components for this item.
components	component[]	no	no	-	BOM components list (custom field type). Used when has_components=true.
branch_id	entity_reference (apps_branch)[]	yes	no	-	Branches where this item is available (required).
unit	list_string	no	no	piece	Unit of measurement. Allowed: piece, pack, gram, kilogram, milliliter, liter.
sku	string	no	no	-	Stock keeping unit code.
admin_id	entity_reference (user)	no	no	-	Owner/admin user reference.
variation_group_title	string	no	no	-	Variant group title (default language).
variation_id	entity_reference (apps_variation)[]	no	no	-	Variants attached to this item (multiple).
addon_group_id	entity_reference (apps_addon_group)[]	no	no	-	Add-on groups available for this item (multiple).
reward_points	decimal	no	no	-	Reward points configured for the item.
application_id	entity_reference (apps_application)	yes	no	-	The owning application/store id (required).
langcode	language	no	no	-	The language code of Apps entity.
created	timestamp	no	no	-	The time that the entity was created.
changed	timestamp	no	no	-	The time that the entity was last edited.

Notes

• For entity_reference fields, the API commonly returns arrays of { \"target_id\": <id> } and/or expanded referenced entities depending on the formatter logic.
• fields can also include allowed calculated fields, but only from the API v3 known list (otherwise 400 invalid_field).