# Gets an Item by Id Three Endpoints Retrieve Item Data {% table %} --- - GET /items - Multiple items from any store unless filtered --- - GET /items/{itemId} - A specific item from any store --- - GET /stores/{storeId}/items - Multiple items from a specific store unless filtered {% /table %} Caveats Regarding Deleted Items - Items marked as deleted are not returned in the response. - Yellow Dog keeps deleted items in an archive and allows them to be undeleted. Endpoint: GET /items/{id} Version: v3.0: 3.30.0 Security: Auth API User Token ## Path parameters: - `id` (string, required) A valid item id must appear in the path. ## Query parameters: - `Expand` (string) Options: stores, vendors, images, extended-item, dimensions, GTIN Combine a list of one or more Expand option flags by separating them with commas as follows: ?Expand=dimensions,vendors {% table %} --- - stores - Expand the stores array. --- - vendors - Expand the vendors array. --- - images - Expand the images array. --- - extended-item - Expand multiple properties including shortDescription, isEvergreen, style, expirationDays, reference, attributes, etc. --- - dimensions - Expand the dimensions array. --- - GTIN - Expand the epcGTIN array. {% /table %} ## Response 200 fields (application/json): - `id` (string, required) Yellow Dog's primary key for the Item; always unique. When pushing items to the API, if an ItemID is present, Yellow Dog will update or create an item. If ItemID is not present, Yellow Dog will create an item and provide the ItemID in response. ItemID is formatted as a GUID (example: 433ef432-f63e-4c26-a29f-39d4079d9fc9) - `description` (string,null) Main item description in Yellow Dog - `posDescription1` (string,null) Shorter item description for POS terminals; usually limited to 16 characters - `posDescription2` (string,null) Shorter item description for POS terminals; usually limited to 12 characters - `sku` (string,null) Main number associated with the item in the Yellow Dog UI; auto generated by Yellow Dog when the item is created; unique per database - `noCount` (boolean) When true, this item's on hand will always report as zero, and no costs or inventory adjustments will be stored. - `shippingWeight` (number) Shipping Weight of the item. The unit of measure is not specified; this field contains a number only. - `shippingHeight` (number) Shipping Height of the item. The unit of measure is not specified; this field contains a number only. - `shippingWidth` (number) Shipping Width of the item. The unit of measure is not specified; this field contains a number only. - `shippingLength` (number) Shipping Length of the item. The unit of measure is not specified; this field contains a number only. - `uom` (string,null) Unit of Measure; additional text field used to describe the way an item is measured; not often used because we use Dimension 1 for item size - `childCount` (number) Set how much the parent the Child Item of a Parent/Child relationship. Examples: - Parent Child where the Parent is an Each and the Child is a 2 Pack of the Parent the childCount is .5 (1/2). - Parent Child where the Parent is an Each and the Child is a Case Size of 24 the childCount is 0.041666666667 (1/24) - `childUsage` (number) This is the expected usage amount of a child item. This should be the decimal representation of the percentage.This defaults to 1.0 (100%) - `upc` (array,null) - `active` (boolean) True=Item is active in Yellow Dog; False=Item is inactive in Yellow Dog; inactive items can have an on hand count, but are not sold at the POS; this is generally used for seasonal or special event items that are only sold at specific times - `lastUpdated` (string,null) DateTime when this item was last updated in Yellow Dog, in ISO 8601 format. This is not impacted by changes of an Item's onhand value. This is used to indicate when a change to an items configuration has been adjusted. Example Scenarios that would trigger a lastUpdated value change: - Changing an Item's Dimension - Making an Item available to a Store - Adjusting the Item's Retail Price for a Store - Adjusting the Item's Default Retail Price - Changing the Item's Level Assignment - Adjusting an Interface for an Item's Store Example Scenarios that would not trigger a lastUpdated value change: - Item being Sold as part of a Transaction - Item included on an Invoice, Receipt, Purchasing Order Document - `dimension1` (object) - `dimension1.id` (string) DimensionID is the unique identifier for the Dimension; formatted as GUID (example: 433ef432-f63e-4c26-a29f-39d4079d9fc9) - `dimension1.description` (string,null) Description of the Dimension - `dimension2` (object) - `dimension3` (object) - `dimension4` (object) - `dimension5` (object) - `dimension6` (object) - `dimension7` (object) - `dimension8` (object) - `dimension9` (object) - `dimension10` (object) - `level` (object) Level is a hierarchy of groupings that are used for reporting and third party interface purposes - `level.id` (string) LevelID is the unique identifier for the Level; formatted as GUID (example: 433ef432-f63e-4c26-a29f-39d4079d9fc9) - `level.code` (string,null) - `level.description` (string,null) Description of the Level to which the item belongs - `level1` (object) Level is a hierarchy of groupings that are used for reporting and third party interface purposes - `level2` (object) Level is a hierarchy of groupings that are used for reporting and third party interface purposes - `level3` (object) Level is a hierarchy of groupings that are used for reporting and third party interface purposes - `level4` (object) Level is a hierarchy of groupings that are used for reporting and third party interface purposes - `parentItem` (object) - `parentItem.id` (string) - `recipe` (object) - `matrix` (object) - `webProperties` (object) - `webProperties.title` (string,null) Main item description for the item in the web cart; limited to 256 characters; can be HTML if the user specifies formatting in text areas - `webProperties.description` (string,null) A short text description for the item, to be displayed in the web cart; can be HTML if the user specifies formatting in text areas - `webProperties.extendedDescription` (string,null) A longer text description for the item, to be displayed in the web cart; can be HTML if the user specifies formatting in text areas - `webProperties.availableDate` (string,null) DateTime when the item will start to be available to the web cart, in ISO 8601 format - `webProperties.expiresDate` (string,null) DateTime when the item will stop being available to the web cart, in ISO 8601 format. - `webProperties.sale` (boolean) True= This item is on sale and should be sold at either the ItemSaleRetail or ItemSalePercentOff, whichever is present; False=This item should be sold at it's store retail price. - `webProperties.itemSaleRetail` (number,null) Web Sale price; used only when Sale=True; an item can only have either ItemSaleRetail or ItemSalePercentOff, not both - `webProperties.itemSalePercentOff` (number,null) Web sale discount percentage; used when Sale=True; an item can only have either ItemSaleRetail or ItemSalePercentOff, not both - `webProperties.saleBegins` (string,null) DateTime when the Web Sale will begin, in ISO 8601 format - `webProperties.saleEnds` (string,null) DateTime when the Web Sale will end, in ISO 8601 format - `webProperties.available` (boolean) True=This item is available to be sold in the Web Cart; False=This item is not available to be sold in the web cart - `webProperties.flagA` (boolean) True=This item should be designated as Flag A in the web cart; False=This item should not be designated as Flag A in the web cart - `webProperties.flagB` (boolean) True=This item should be designated as Flag B in the web cart; False=This item should not be designated as Flag B in the web cart - `webProperties.flagC` (boolean) True=This item should be designated as Flag C in the web cart; False=This item should not be designated as Flag C in the web cart - `webProperties.tags` (string,null) - `webProperties.productType` (string,null) - `stores` (array,null) Items have specific store availability and can have different on hand counts, retail prices, and costs per store This is only available when expand vendors is passed in the query string. example: /items?Expand=Stores - `stores.id` (string) Yellow Dog's primary key for the Store; always unique; formatted as GUID (example: 433ef432-f63e-4c26-a29f-39d4079d9fc9) - `stores.bin` (string,null) - `stores.reorderPoint` (number) - `stores.parLevel` (number) - `stores.tariffCode` (string,null) - `stores.description` (string,null) Main store description in Yellow Dog - `stores.code` (string,null) Main number associated with the store in the Yellow Dog UI; unique per database - `stores.revenueCenterNumber` (string,null) The code used by the third party system that corresponds to their store/location ID - `stores.onHand` (number) ___WARNING: This value represents a count of inventory that may be hours old because it is not refreshed frequently.___ The latest on hand information for this item or any items since a specified time is accomplished using the POST /inventory endpoint. - `stores.retailPrice1` (number) - `stores.retailPrice2` (number) - `stores.retailPrice3` (number) - `stores.retailPrice4` (number) - `stores.retailPrice5` (number) - `stores.retailPrice6` (number) - `stores.retailPrice7` (number) - `stores.retailPrice8` (number) - `stores.retailPrice9` (number) - `stores.retailPrice10` (number) - `stores.flags` (array,null) Flags designate storage locations, such as Walk-In, Storage Closet, Freezer, etc., making ordering and physical inventories easier - `stores.interfaces` (object,null) These are values that can be set differently per third party system; these values correspond to Yellow Dog's Generic Level A-C and Code A-G, which can be individually named in Yellow Dog to fit your system's naming scheme. For example, if your system has a Major Category, you can rename Generic Level A to Major Category, and you may have Major Category codes and descriptions like 200 Retail, 300 Golf, etc. - `stores.additionalInterfaces` (array,null) List of interfaces that appear to be set to two values In some scenarios it is possible for an Interface to be set to two different values. When this happens the initial value received is added to the Interfaces property:value. Any additional settings will be added to the AdditionalInterfaces as a list of KeyValuePairs. - `stores.additionalInterfaces.key` (string,null) - `stores.additionalInterfaces.value` (string,null) - `vendors` (array,null) Items are assigned to at least one specific vendor in Yellow Dog. This is only available when expand vendors is passed in the query string. example: /items?Expand=Vendors - `vendors.id` (string) Yellow Dog's primary key for the Vendor; always unique; formatted as GUID (example: 4c3ef432-f63e-4c26-a29f-39d4079d9fc9) - `vendors.code` (string,null) Main number associated with the vendor in the Yellow Dog UI; unique per database - `vendors.description` (string,null) Main vendor description in Yellow Dog - `vendors.sku` (string,null) Vendor's unique ID for the item - `vendors.price` (number) Vendor's Price for the item - `vendors.isPrimary` (boolean) - `images` (array,null) - `images.placement` (integer) - `images.id` (string,null) - `images.description` (string,null) - `images.imageURL` (string,null) - `shortDescription` (string,null) Short Description of the item; this is a free form text field that should describe the item in less characters than the item.Description. This is commonly used for smaller screen devices or when a more concise description is needed. This value is only available when the expand option extended-item is passed in the query string example: /items?Expand=extended-item - `isEvergreen` (boolean,null) Evergreen items are items that do not expire or do not "Age". This indicator is used to help manage the items that are always good for inventory or do not turn by season/year. This value is only available when the expand option extended-item is passed in the query string example: /items?Expand=extended-item - `style` (string,null) Style code of the item. This is used to group like items together, such as a matrix of shirts that all have the same Style code/number. This value is only available when the expand option extended-item is passed in the query string example: /items?Expand=extended-item - `expirationDays` (number,null) Generally, how many days before this type of item expires once added to inventory. This value is only available when the expand option extended-item is passed in the query string example: /items?Expand=extended-item - `reference` (string,null) Free text field for additional reference notes or identifiers. Reference has no specific business use within YDI. Use this field to record other necessary, customer-specific information. This value is only available when the expand option extended-item is passed in the query string example: /items?Expand=extended-item - `attributes` (array,null) The item attributes property is essentially an array of key-value pairs with some extra details. The key of each key-value pair is given by its description property. The value appears in its value property. Note that the type of this value depends on the type given when the attribute was defined. This type is specified by the datatype property as a string name. The example given shows an attributes array with one element of each of eight datatypes: string, bool, int, float, date, time, datetime, and select. A duplicate copy of the value appears in a property whose name corresponds to the datatype. An id property contains a GUID that can serve as an alternate key. This id does not change even if the description property is edited. A helpText property is a copy of the corresponding property in the attribute type definition. An attributeCount property is a count of values associated with this instance of the attribute. With the select datatype, attributeCount is the number of elements in the attribute value's array of strings corresponding to names defined for up to ten checkboxes. Users of the YdInv app can specify item attribute type definitions which become available to all items in the database. When editting items, they can then select item specific values for each each of these attribute types. Data only appears in this attributes array when the expand option extended-item is passed in the query string. For example: /items?Expand=extended-item Example: [{"description":"Fair Trade Statement","datatype":"string","value":"This product is sourced from fair trade growers and is certified by Fair Trade International.","string":"This product is sourced from fair trade growers and is certified by Fair Trade International.","attributeCount":1,"helpText":"Provides a statement concerning fair trade sourcing.","id":"01234567-dddd-eeee-ffff-aaaabbbb0001"},{"description":"Contains Alcohol","datatype":"bool","value":true,"bool":true,"attributeCount":1,"helpText":"Specifies whether this product contains alcohol.","id":"01234567-dddd-eeee-ffff-aaaabbbb0002"},{"description":"Maximum stacked units","datatype":"int","value":5,"int":5,"attributeCount":1,"helpText":"Specifies how many of these items may be stacked vertically.","id":"01234567-dddd-eeee-ffff-aaaabbbb0003"},{"description":"Case weight in pounds","datatype":"float","value":31.5,"float":31.5,"attributeCount":1,"helpText":"Specifies the weight of one case of this item in pounds.","id":"01234567-dddd-eeee-ffff-aaaabbbb0004"},{"description":"Release date","datatype":"date","value":"2025-10-20","date":"2025-10-20","attributeCount":1,"helpText":"Specifies the original release date of this item.","id":"01234567-dddd-eeee-ffff-aaaabbbb0005"},{"description":"Last call cutoff","datatype":"time","value":"22:00:00","time":"22:00:00","attributeCount":1,"helpText":"After this time of day, in local time, the product is not for sale until the next day.","id":"01234567-dddd-eeee-ffff-aaaabbbb0006"},{"description":"Online ticket availability","datatype":"datetime","value":"2025-10-20T14:45:06Z","datetime":"2025-10-20T14:45:06Z","attributeCount":1,"helpText":"This ticket item goes open for online sales at this time.","id":"01234567-dddd-eeee-ffff-aaaabbbb0007"},{"description":"Allergen Information","datatype":"select","value":["Contains Gluten","Contains Peanuts","Contains Soy"],"select":["Contains Gluten","Contains Peanuts","Contains Soy"],"attributeCount":3,"helpText":"Identifies ingredients that may cause allercic reactions.","id":"01234567-dddd-eeee-ffff-aaaabbbb0008"}] - `attributes.description` (string,null, required) A descriptive name for the attribute type. Serves as the key in each key-value pair. - `attributes.datatype` (string, required) This string identifies a type for the attribute value. - `attributes.value` (string,boolean,integer,number,array, required) This string identifies a type for the attribute value. - `attributes.string` (string) If present, the attribute type is a text string whose value appears in this property. - `attributes.bool` (boolean) If present, the attribute type is boolean with a value of true or false appearing in this property. - `attributes.int` (integer) If present, the attribute type is an integer whose value appears in this property. - `attributes.float` (number) If present, the attribute type is a real number whose value appears in this property. - `attributes.date` (string) If present, the attribute type is an ISO 8601 date string whose value appears in this property. - `attributes.time` (string) If present, the attribute type is a real number whose value appears in this property. - `attributes.datetime` (string) If present, the attribute type is a real number whose value appears in this property. - `attributes.select` (array) If present, the attribute type is a set of up to ten checkbox options whose value appears in this property as an array of strings corresponding to the checkboxes that are selected for the item. - `attributes.attributeCount` (integer, required) When datatype is select, this is a count of selections in the value array. This count is 1 if the item contains an attribute of any other datatype. - `attributes.helpText` (string, required) Contains a copy of the helpText property from the corresponding attribute type definition. - `attributes.id` (string, required) Uniquely identified the corresponding attribute type definition.. - `dimensions` (object,null) This value is only available when the expand option Dimensions is passed in the query string example: /items?Expand=Dimensions - `epcGTIN` (array,null) GTIN (Global Trade Item Number) values for the item; returns as an array of 14-digit GTIN codes This value is only available when the expand option GTIN is passed in the query string and requires database version 377 or above example: /items?Expand=GTIN ## Response 404 fields (application/json): - `type` (string,null) - `title` (string,null) - `status` (integer,null) - `detail` (string,null) - `instance` (string,null) ## Response 500 fields (application/json): - `message` (string,null) - `errors` (array,null) - `errors.message` (string,null) - `errors.extensions` (string,null) ## Response 429 fields