# 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): If you are looking to only pull item data for a single store, it is highly recommended 
to use the /store/:storeId/items endpoint located in the 'Stores' Endpoint Section.

This endpoint will not end back items that are marked as deleted. In the Yellow Dog
Inventory system, the items are soft deleted and are able to be marked as undeleted. 

### Example Requests
/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 call example to refresh your datastore with only the changes that 
have occured in the item configuration.

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

This request will return all the items that have a lastUpdated later than 2024-05-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)

## 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.