# Pull Items via API

*The following explains how to pull item data from Yellow Dog via the Fetch API.*

## Overview

When pulling items from Yellow Dog’s Fetch API, there are four standard endpoints to use:

1. Stores - This can be used in two ways
  - GET StoreIDs to map to your Locations
  - GET stores/{id}/items to get items in a specific store, such as the Primary Store
    - Expand the Stores array to see store-specific interfaces and retail prices
    - Filter by lastUpdated to only get items updated since your last pull
2. ThirdPartyCodes - POST integration-specific codes that will be assigned to items via Store/Level in Yellow Dog, such as [YourCompany/POSName]_Publish, as well as [YourCompany/POSName]_Category, [YourCompany/POSName]_TaxGroup, etc.
  - See https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/post-interfaces-thirdpartycodes for more information
3. Items - GET item data
  - Expand the Stores array to see all stores the item is available to, along with store-specific interfaces and retail prices
  - Filter by lastUpdated to only get items updated since your last pull
4. Inventory - ONLY IF PULLING ON HANDS FROM YELLOW DOG
  - POST to this endpoint to get the most up to date on hands based on store and/or item


## Stores

Your integration will need some method of mapping Yellow Dog Stores to locations in your system via the Yellow Dog Store GUID.

This way you will be able to limit your queries to the Yellow Dog Stores being used by your integration,
as there may be additional stores in the Yellow Dog database that will not be used for your integration for various reasons.

Note that the Yellow Dog Store GUID is not visible to the client in Yellow Dog's UI, so when getting a store's ID from the Stores endpoint
you will also want to get the store's Code and Description to make them recognizable to the client when they confirm the mapping.

### Primary Store

In Yellow Dog, items can have store-specific settings such as interfaces (also known as Third Party Codes), retail price, and store availability.

To simplify setup and maintenance for the customer, and to simplify the integration code,
it is standard practice to support a designated Primary Store for the integration.

Note that there is not a designator in Yellow Dog’s code that makes a store a Primary Store.

This is something that would need to be decided on with the customer before installing the integration
and you would have to have some way to set it for your code using Yellow Dog’s GUID for the store.

- For the customer, this means that
  - all items they want to be pulled from Yellow Dog into your system will need to be available to the designated Primary Store in Yellow Dog
  - The [YourCompany/POSName]_Publish interface will need to be set to true in the Primary Store
so that the client won’t have to set this in each Yellow Dog store that the item is available to
  - Any other non-location specific interfaces (thirdPartyCodes) for the integration will be set in the Primary Store
  - If location-specific retail pricing is not supported in your system, they will be trained to set RetailPrice1 in the Primary Store for this integration
- For your integration, this means that
  - When determining which items to pull into your system, you can use the stores/{id}/items endpoint for the Primary Store
    - As long as [YourCompany/POSName]_Publish interface is true for the item in the Primary Store, you would pull that item into your system
    - Any other non-location-specific interfaces can also be pulled from that same endpoint
    - If location-specific retail pricing is not supported in your system, you would also pull retailPrice1 from the Primary Store
  - If you are supporting location-specific retail or location availability, you will need to get those from the Items endpoint
with the stores array expanded to see all stores the item is available to


For more information about Third-Party Codes (Interfaces), see https://developer.yellowdogsoftware.com/rest/user-guide/05-pos-integrations/item-annotation.

## Endpoints That Retrieve Item Data

| 
| [GET /items](/rest/fetch/api/items/get-items) | Multiple items from any store unless filtered |
| [GET /items/{itemId}](/rest/fetch/api/items/get-items-byid) | Details on a specific item from any store given its item `id` GUID. |
| [GET /stores/{storeId}/items](/rest/fetch/api/stores/get-stores-items) | Multiple items from a specific store unless filtered |


Of the above three endpoints that are able to retrieve item data, a two-way POS
integration will generally use either
[GET /items](/rest/fetch/api/items/get-items) or
[GET /stores/{storeId}/items](/rest/fetch/api/stores/get-stores-items).
If all of the item data that the POS is interested in can be found in one store,
[GET /stores/{storeId}/items](/rest/fetch/api/stores/get-stores-items) will help
narrow the results to the relevant data. Otherwise,
[GET /items](/rest/fetch/api/items/get-items) can return all item data in the entire
database and the caller can take care of filtering what is needed.

Since the query parameters supported by these two endpoints are the same, it is
relatively easy to start with either endpoint and change your mind later if necessary.

## Start with all items then get limited updates

### Paginate through all of this store's items

`GET /stores/{storeId}/items?Expand=Stores&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 have occured in the item configuration.

### Limit Subsequent Item Pulls with `lastUpdated`

`GET /stores/{storeId}/items?Expand=Stores&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.

Note that if the update request does not specify pagination parameters, it will return
no more than the default page size of 100 items. For this reason, you should at least
check the response headers to make sure you have not missed any items in an update due
to this limit.
The frequency at which you check for updates will also influence the typical count
in an update response and how much time goes by without having the latest item data.

## Include store specific item data

When pulling item data, make sure to use the `?Expand=Stores` query parameter to
include store specific data.
Even if you only care about the item data for one store,
you will need this expansion parameter to get pricing information since
Yellow Dog lists it under store specific data.

## POS specific item data

Yellow Dog allows a POS to define its own Third Party Code / Interface requirements to
add POS specific data to items.
See [How to include POS specific item annotations](/rest/user-guide/05-pos-integrations/item-annotation) for details.

## Item Data Points

When pulling items from Yellow Dog into your point of sale system, the following are the recommended Item fields to use in your integration:

| 
| id | This is the unique GUID for the item in Yellow Dog.
If you want to support the ability for the Yellow Dog user to change the SKU for the item in Yellow Dog and still be able to match the Yellow Dog item to the corresponding item in your system, save Items.id as a hidden id for the item in your system.
*NOTE: this is not a visible or editable field in Yellow Dog.* |
| posDescription1 | This should be used as the main description/name of the item in the POS. This is preferable to using Items.description because posDescription1 will be more unique, specifically at sites that use matrices in Yellow Dog. Matrices are groupings of items that share certain characteristics including description. posDecription1 is auto-generated in Yellow Dog based on a formula that is most commonly a condensed version of the description followed by size and color. |
| posDescription2 | Recommended as a potential additional description/name for the item in the POS. Like posDescription1, posDescription2 is auto-generated in Yellow Dog based on a formula and is most often shorter than posDescription1. |
| sku | SKU is a unique value in Yellow Dog and is visible to users in Yellow Dog. It is often used as a barcode by our customers so it should be scannable in the POS.
This is also used when posting transactions to our API in order for sales to match to Yellow Dog items automatically. |
| upc | There is no limit to the number of UPCs that can be assigned to an item in Yellow Dog and they are listed in an array for each item in the items or stores/{id}/items endpoints.
It is recommended that
SKU be included as a UPC at the POS to ensure that it is scannable.
But if only one UPC is supported per item in the POS system, it is recommended that the first UPC from the UPC array for the item is used, and if there aren’t any UPCs assigned to the item, that SKU is used as the UPC. |
| active | In Yellow Dog, items are Active by default, but can be set to Inactive if the item is seasonal and won’t be counted or sold in its off season, for example.
This field can be used by your integration to determine whether the item should be available at the POS or not. |
| matrix.id | *OPTIONAL* - In Yellow Dog, items can be created as a group called a matrix.
This is used for retail items such as shirts that share the same style but are available in multiple sizes and/or colors.
All items that are part of a matrix in YD will have a matrix.id, but are also individual items.
As a result, your integration can pull them in as individual items or,
if your system supports something like a matrix with a main product and its variants,
you can use the matrix.id to group the matrix items in your system as well. |
| stores | In the Items endpoint, the items.stores array should be expanded to see all of the YD stores that the item is available to, along with the item’s per store settings, such as retail price and interfaces (assigned Third Party Codes) |
| stores.id | This the the unique GUID for the store in Yellow Dog. This is NOT visible to users in Yellow Dog, and is the most accurate way to identify stores in your code.
If the stores.id appears in the stores array for the item that means that the item is available to that store in Yellow Dog. |
| stores.retailPrice1 | In Yellow Dog items can have multiple different retail prices per store, but with POS integrations it is most common that only stores.retailprice1 is used.
Again, this can be different per store for the same item in Yellow Dog, so if your system only supports a single retail price per item (and does not support per-location pricing), it is recommended that your integration uses a designated Primary Store from which it will pull retail price for the item. |
| stores.interfaces | In Yellow Dog, interfaces are integration-specific codes assigned to items, normally at the store or at the level in Yellow Dog, where they are then inherited by the items under that store/level.
Interfaces are also known as Third Party Codes in Yellow Dog's API, and when a third party pulls items from our API it is standard practice for them to have a minimum of one third party code that they post to our API’s ThirdPartyCodes endpoint as part of installation for their integration.
See the section of the User Guide on Third Party Codes / Interfaces for more information. |