# Items

Product information that is tracked in Yellow Dog Inventory.

## Gets all Items

 - [GET /items](https://developer.yellowdogsoftware.com/rest/fetch/api/items/get-items.md): 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.






#### Parameters and Headers
This endpoint supports standard
paginaton query parameters and response headers.
In addition, it supports item specific use of the query parameters listed below.


 Using Pagination with 'lastUpdated' 

##### Paginate through all items

GET /items?Expand=Stores&Expand=Vendors&orderBy=sku&pageNumber=1&pageSize=100

For populating your initial datastore, it is best to make a call through all pages of the
items endpoint with the proper expansion query parameters.
From this point forward, you should be able to use the following lastUpdated
example to refresh
your datastore with only the changes that \r\nhave occured in the item configuration.

##### Limit Subsequent Item Pulls with lastUpdated

GET /items?Expand=Stores&Expand=Vendors&orderBy=sku&filter=lastUpdated>=20260401

This request will return all the items that have a lastUpdated later than 2026-04-01.
It is highly recommended that you use a request like this for updating your data store
for the latest item configurations.
It is recommended that the lastUpdated filter value be set as the last time the item refresh cycle began.

## Upserts Items in bulk

 - [PATCH /items](https://developer.yellowdogsoftware.com/rest/fetch/api/items/patch-items.md): This endpoint allows for bulk upserting of item configuration changes.

Creating items does have a different set of fields that are required than updating. 
            
### Creating an Item
The fields that are required to create an item are as followed: itemSku, defaultVendorCode, defaultVendorCost, levelCode, description, initialStoreCode, and dimension1Desc.

### Updating an Item
The only field that is required for an update is the itemSku field as that is what is used for matching to an existing item for updating. Any fields that are not supposed to be updated should be passed in as a null or omitted from the body of the request.
            
### Validation Errors
Any kind of data validation will be passed back as a body response similar to the following.
            
json
{
   "Message": "Unable to import item configs at this time",
   "Errors": [
    {
       "Message": "error processing item configurations",
       "Extensions": [
        {
            "errorText": "Value:317 does not match an existing vendor/manufacturer code.",
            "field": "manufacturerCode"
        }
    ]
   }
  ]
}

            
This validation error reflects that the manufacturerCode value does not exist as a valid vendor code in the Yellow Dog Inventory Instance.
            
When a validation error occurs then the entire request will fail.
            
### Additional Notes
Processing the item changes can take up to 10 minutes to process due to the amount of background processing that needs to be done.

## Gets an Item by Id

 - [GET /items/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/items/get-items-byid.md): 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.

## Upserts Item Store Configs

 - [PATCH /items/store-configs](https://developer.yellowdogsoftware.com/rest/fetch/api/items/patch-items-store-configs.md)

## Adds an Image as an Attached File to an Item.

 - [POST /items/{itemId}/images](https://developer.yellowdogsoftware.com/rest/fetch/api/items/post-items-images.md): User's client MUST be 366+ with cloud storage enabled

## Updates the Description of an Items Attached File

 - [PATCH /items/{itemId}/images/{imageId}](https://developer.yellowdogsoftware.com/rest/fetch/api/items/patch-items-images-byid.md)

## Deletes an item's image

 - [DELETE /items/{itemId}/images/{imageId}](https://developer.yellowdogsoftware.com/rest/fetch/api/items/delete-items-images-byid.md)

## Adds a new record for an item's retail

 - [POST /items/{id}/retails](https://developer.yellowdogsoftware.com/rest/fetch/api/items/post-items-retails.md): This endpoint allows you to set a new retail price for an item in a store to take effect at a scheduled future time.

It will respond with an error if the given timestamp refers to a time in the past. Please use ISO 8601 compliant timestamps including a timezone suffix of "Z" for UTC or an offset to a local timezone as described in the Getting Started --> Timestamps documentation.