# Fetch API _For differences between versions, see_ [Changelog](./changelog/index.md). # ![REST API logo](../resources/rest-api-cloud-logo.png)
Version: v3.0: 3.30.0 License: proprietary ## Servers Production server ``` https://fetch.yellowdogsoftware.com/api/v3 ``` ## Security ### Auth API User Token JWT Authorization header using the Bearer scheme, use the Auth API for retrieving this token. Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Fetch API](https://developer.yellowdogsoftware.com/_bundle/rest/fetch/api.yaml) ## Accounting Accounting Export Reports that can be consumed by 3rd Party accounting systems ### Gets a listing of Return to Vendors based on Store - [GET /accounting/{storeId}/{date}/returnToVendors](https://developer.yellowdogsoftware.com/rest/fetch/api/accounting/get-returntovendors.md) ### Gets a listing of invoices of a store on a given date - [GET /accounting/{storeId}/{date}/invoices](https://developer.yellowdogsoftware.com/rest/fetch/api/accounting/get-invoices.md) ### Gets revenue of a store on a given date - [GET /accounting/{storeId}/{date}/revenue](https://developer.yellowdogsoftware.com/rest/fetch/api/accounting/get-revenue.md): Gets revenue of a store on a given date, summarized by GL Account. ### Journal Entries for a store - [GET /accounting/{storeId}/{date}/journalEntry](https://developer.yellowdogsoftware.com/rest/fetch/api/accounting/get-journalentry.md): Gets a listing of journal entries of a store on a given date, summarized by GL Account. ### Gets a listing of accounts and their code data - [GET /accounting/{storeId}/codes/{codeType}](https://developer.yellowdogsoftware.com/rest/fetch/api/accounting/get-codes.md) ## AttachedFiles Items and Recipes are able to have images associated to them. ### Gets image based on Id. This image can be associated to an Item or a Recipe. - [GET /attachedFiles/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/attachedfiles/get-attachedfiles-byid.md) ## CountSheets A dynamic list of Items that are designed to aide with physical inventories. Countsheets are based on a static list of items, Levels, and Flags ### Getting Count Sheets - [GET /countsheets](https://developer.yellowdogsoftware.com/rest/fetch/api/countsheets/get-countsheets-all.md) ### Getting a Count Sheet by Id - [GET /countsheets/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/countsheets/get-countsheets-byid.md) ## Currency Operations used to manage currency conversion for the database. These are used when multiple currencies are used in a database. ### Getting Currency - [GET /currency](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/get-currency.md) ### Creating new Currency Exchange Rate - [POST /currency](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/post-currency.md) ### Updating existing Currency Exchange Rate - [PUT /currency](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/put-currency.md) ### Bulk delete Currency Exchange Rates - [DELETE /currency](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/delete-currency.md) ### Getting Effective Exchange Rate - [GET /currency/effectiveExchangeRate/{currencyCode}](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/get-currency-exchange.md) ### Getting Currency by Id - [GET /currency/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/get-currency-byid.md) ### Deleting a Currency Exchange Rate - [DELETE /currency/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/currency/delete-currency-byid.md) ## Dimensions Attributes that are available for assigning to an Item. Attributes can be like a Size or Color. ### Getting Dimensions - [GET /dimensions](https://developer.yellowdogsoftware.com/rest/fetch/api/dimensions/get-dimensions.md) ### Creating new Dimensions - [POST /dimensions](https://developer.yellowdogsoftware.com/rest/fetch/api/dimensions/post-dimensions.md) ### Creating new Dimensions - [PUT /dimensions](https://developer.yellowdogsoftware.com/rest/fetch/api/dimensions/put-dimensions.md) ### Getting Dimension by Id - [GET /dimensions/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/dimensions/get-dimensions-byid.md) ### Deleting a Dimension (deprecated) - [DELETE /dimensions/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/dimensions/delete-dimensions-byid.md) ## Flags Flags allow you to indicate storage locations, making ordering and physical inventories easier. ### Getting Flags - [GET /flags](https://developer.yellowdogsoftware.com/rest/fetch/api/flags/get-flags.md) ### Getting Flag by Id - [GET /flags/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/flags/get-flags-byid.md) ## Inventory Item Inventory OnHand information. ### Gets all Inventory - [POST /inventory](https://developer.yellowdogsoftware.com/rest/fetch/api/inventory/post-track-inventory.md): This endpoint is recommended for any frequent polling of item onhands. Although the GET Items endpoint includes a stores onhand value, the onhand value being changed does not trigger an update of the rowUpdated for that endpoint. This endpoint uses pagination to limit the amount of items that are returned in a response. The use of these values is similar to how the query string pagination works in other endpoints, however these are a component of the response body. Note: As they do not use a query string for pagination, the pagination headers used in other endpoints will not work for this. Recommended use case is to pull at a known pageSize and stop when the returned item array is less than the requested pageSize. ### Example Request Body for Common Usage Scenarios #### Get an Item's onhand in a particular Store json { "pageNumber": 1, "pageSize": 100, "stores": [ ":storeId" ], "items": [ ":itemId" ] } #### Get an Stores Onhands updated since a certain date json { "pageNumber": 1, "pageSize": 100, "stores": [ ":storeId" ], "rowUpdated": "2024-05-24" } #### Get all Current onhands for all Stores and Items based on the last pulled date json { "pageNumber": 1, "pageSize": 100, "lastUpdated": "2024-03-05T06:06:58.529Z" } or json { "pageNumber": 1, "pageSize": 100, "lastUpdated": "2024-03-05T06:06:58.529-05:00" } or json { "pageNumber": 1, "pageSize": 100, "lastUpdated": "2020-05-29 00:00:00" } #### Get the Current onhand for a particular Item across all Stores. json { "pageNumber": 1, "pageSize": 100, "items": [ ":itemId" ] } ## Invoices A Purchasing document ### Create a Staged Invoice via a file upload - [POST /invoices/ocr](https://developer.yellowdogsoftware.com/rest/fetch/api/invoices/post-invoices-ocr.md) ### Creates new staged invoice lines for a given staged invoice. - [POST /invoices/staged/{stagedInvoiceId}/lines](https://developer.yellowdogsoftware.com/rest/fetch/api/invoices/post-invoices-staged-byid-lines.md) ### Find the original document for a staged invoice with the specified ID. - [GET /invoices/staged/{stagedInvoiceId}/original-document](https://developer.yellowdogsoftware.com/rest/fetch/api/invoices/get-invoices-staged-byid-original-document.md) ### Updates a staged invoice with the specified ID. - [PUT /invoices/staged/{stagedInvoiceId}](https://developer.yellowdogsoftware.com/rest/fetch/api/invoices/put-invoices-staged-byid.md): This endpoint requires the user to be authenticated and have the Api.Helpers.YdPolicyName.atLeast377 policy. The updated staged invoice is returned in the response body if the operation is successful. If the staged invoice was not modified, a 304 Not Modified status code is returned. If a validation error occurs, a 422 Unprocessable Entity status code is returned. If the database schema version is not version 377 or greater, a 403 Forbidden status code is returned. ### Updates a staged invoice with the specified ID. - [PATCH /invoices/staged/{stagedInvoiceId}](https://developer.yellowdogsoftware.com/rest/fetch/api/invoices/patch-invoices-staged-byid.md) ## ItemAliases UPCs or additional SKUs to for an Item. ### Adding Item Aliases - [POST /itemaliases](https://developer.yellowdogsoftware.com/rest/fetch/api/itemaliases/post-itemaliases.md) ## 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. ## ManualAdjusts A Manual Adjustment will affect an Item's OnHand. ### Creates Manual Adjustments - [POST /manualadjusts](https://developer.yellowdogsoftware.com/rest/fetch/api/manualadjusts/post-manualadjusts.md) ## MetaInfo Database specific configuration information ### Get all Meta Information for YDI Interface - [GET /metainfo](https://developer.yellowdogsoftware.com/rest/fetch/api/metainfo/get-metainfo.md): In Yellow Dog, the user is able to configure the Names that are used on buttons to make the user interface more friendly for their particular use. This endpoint will display the values of these name changes. Common examples of this are: - Dimension 1 is named Size in the Yellow Dog Interface, Dimension 1 (Size) will be index 0 of the dimensions array. - Flag is named Location ## ProductionGroups Collections of production groups. ### Get ProductionGroups - [GET /productiongroups](https://developer.yellowdogsoftware.com/rest/fetch/api/productiongroups/get-productiongroups.md): Production Groups indicate which team produces the recipe. ## PurchaseOrders A Purchasing document ### Starts the Tiered Purchase Order Approval process - [POST /purchaseOrders/{id}/requestTieredApproval](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/post-purchaseorders-tieredapproval-request.md) ### Approves a Purchase Order Tier - [PUT /purchaseOrders/tieredApproval](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/put-purchaseorders-tieredapproval.md) ### Gets Purchase Orders - [GET /purchaseOrders](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/get-purchaseorders.md): Example use cases api/v2/purchaseOrders?pageNumber=1&pageSize=100&Filter=committed>2024-03-05T06:06:58.529Z&Filter=lastUpdated>2024-03-06&orderBy=committed will get the first page of purchase orders where the committed date is later than 2024-03-05T06:06:58.529Z AND the lastUpdated date is later than 2024-03-06T00:00:00Z, ordering by the committed date /api/v2/purchaseOrders?pageNumber=1&pageSize=100&Filter=committed>2024-03-05T06:06:58.529Z&orderBy=committed will get the first page of purchase orders where the committed date is later than 2024-03-05T06:06:58.529Z ordering by the committed date. ### Creates Purchase Orders. - [POST /purchaseOrders](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/post-purchaseorders.md) ### Get Purchase Order by Id - [GET /purchaseOrders/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/get-purchaseorders-byid.md) ### Get Purchase Order by token - [GET /purchaseOrders/byToken](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/get-purchaseorders-bytoken.md) ### Get Purchase Order Approval Status by Id of Purchase Order - [GET /purchaseOrders/{id}/approvalStatus](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/get-purchaseorders-approvalstatus-byid.md) ### Get Purchase Order Approval Status using token - [GET /purchaseOrders/approvalStatusByToken](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/get-purchaseorders-approvalstatus-bytoken.md) ### Update Committed Purchase orders - [PATCH /purchaseOrders/updateCommitted](https://developer.yellowdogsoftware.com/rest/fetch/api/purchaseorders/patch-leafroute.md): Infrequently there are use cases where a previously committed purchase order would be allowed to have new Lines added or other adjustments to the document. The following properties of a committed purchase order are prohibited from being updated - Commdoc - Committed Status - Committed Date Time - Vendor - Store - Arrival Log The following requirements in place for a purchase order to be edited using this method. - User making the request has the appropriate permissions to edit Purchase Orders after Commit. - Only purchase orders that have been committed but do not have any kind of purchasing activity against them will be allowed to be edited. ## Receipts A Receiving document ### Gets Receipts - [GET /receipts](https://developer.yellowdogsoftware.com/rest/fetch/api/receipts/get-receipts.md) ### Create Receipts - [POST /receipts](https://developer.yellowdogsoftware.com/rest/fetch/api/receipts/post-receipts.md): Using this endpoint will create uncommitted receipts. Marking a receipt as committed and thus making the associated adjustments to the item inventory will need to be performed using the Yellow Dog Inventory Client. ### Requirements The following properties must exist in the database in order to be uploaded to a receipt: * Store * Vendor * Items The following requirements are needed for a receipt to be created using this method: * The user making the request has the appropriate Edit permission to the Receipt Editor, in the store that the receipt is being created in. * Only purchase orders that have been committed can be backlinked to a receipt ### BackLinking One common example of backlinking is when a process exists for a location to have a purchase order created for all receipts and purchases of inventory items. This is accomplished by creating a related document for a receipt. In Yellow Dog Inventory, we track the linkage of purchasing documents by the individual lines of a document. To accomplish this, all lines of an existing purchasing document should be marked as the backlink of another document in the process. In example: Given an existing Committed Purchase Order of the following shape. json { "CommdocId": "123e4567-e89b-12d3-a456-426655440025" "type": "PurchaseOrder", "lines": [ { "CommDocLineId": "456e0001-e89b-12d3-a456-426655440000", "quantity": 15, "ItemID":"789e0001-e89b-12d3-a456-426655440000" } ] } Can be fully recieved by sending the following general shape. Notice that the backlinkLineId of the receipt line. json { "type": "Receipt", ..., "lines": [ { "quantity": 15, "ItemID": "789e0001-e89b-12d3-a456-426655440000" "backLinkLineID": "456e0001-e89b-12d3-a456-426655440000" } ] } ### Get Receipt by Id - [GET /receipts/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/receipts/get-receipts-byid.md) ## Recipes Collections of items and recipes, with quantities, that are used to create other items. ### Adds an Image as an Attached File to a recipe User's client MUST be 366+ with cloud storage enabled - [POST /recipes/{recipeId}/images](https://developer.yellowdogsoftware.com/rest/fetch/api/recipes/post-recipes-images.md) ### Updates image details of a recipe - [PATCH /recipes/{recipeId}/images/{imageId}](https://developer.yellowdogsoftware.com/rest/fetch/api/recipes/op-recipes-images-byid.md) ### Deletes a recipe's image - [DELETE /recipes/{recipeId}/images/{imageId}](https://developer.yellowdogsoftware.com/rest/fetch/api/recipes/delete-recipes-images-byid.md) ### Gets Recipes - [GET /recipes](https://developer.yellowdogsoftware.com/rest/fetch/api/recipes/get-recipes.md): This endpoint only returns the list of Recipes, without Ingredients, AttachedFiles, and Links. If the ingredients are needed, then make an another API call to GET Recipe By ID with the Expand=Ingredients option. If the attached files are needed, then make an another API call to GET Recipe By ID with the Expand=AttachedFiles option. If the links are needed, then make an another API call to GET Recipe By ID with the Expand=Links option. Multiple expand options can be used. For example: /recipes/:id?Expand=Ingredients&Expand=AttachedFiles&Expand=Links ### Gets a Recipe By ID - [GET /recipes/{recipeId}](https://developer.yellowdogsoftware.com/rest/fetch/api/recipes/get-recipes-byid.md) ## RecipeTypes Collections of RecipeTypes. ### Get RecipeTypes. - [GET /recipetypes](https://developer.yellowdogsoftware.com/rest/fetch/api/recipetypes/get-recipetypes.md): RecipeType is a way to organize recipes into groups. ## Requests A requisition for purchasing or transfering an item. ### Creates and commits a Request to be used in the Purchasing Document Workflow. - [POST /requests](https://developer.yellowdogsoftware.com/rest/fetch/api/requests/post-requests.md) ### Commits a Request, this allows the Request to be used in future steps of the Purchasing Document Workflow - [PATCH /requests/{id}/Commit](https://developer.yellowdogsoftware.com/rest/fetch/api/requests/patch-requests-commit.md) ### Getting Request Details By ID - [GET /requests/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/requests/get-requests-byid.md) ### Updates an existing Request - [PATCH /requests/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/requests/patch-requests-byid.md) ## Sessions Associate a count to an Item, these sessions can be used for Purchasing Documents or Physical Inventories. ### Getting Sessions - [GET /sessions](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/get-sessions.md) ### Creating new Sessions - [POST /sessions](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/post-sessions.md) ### Updating existing Sessions - [PUT /sessions](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/put-sessions.md) ### Getting Session by Id - [GET /sessions/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/get-sessions-byid.md) ### Deleting a Session - [DELETE /sessions/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/delete-sessions-byid.md) ### Adding a Session Item to a Session - [POST /sessions/{id}/sessionItems](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/post-sessions-sessionitems.md) ### Updating values of a Session Item - [PUT /sessions/{id}/sessionItems/{sessionItemId}/count](https://developer.yellowdogsoftware.com/rest/fetch/api/sessions/put-sessions-sessionitems-count.md) ## Stores Business Entities or locations of a single business entity that need to maintain their own inventory records. ### Gets Stores - [GET /stores](https://developer.yellowdogsoftware.com/rest/fetch/api/stores/get-stores.md) ### Gets Store by Id - [GET /stores/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/stores/get-stores-byid.md) ### Gets Items for a Specific Store - [GET /stores/{id}/items](https://developer.yellowdogsoftware.com/rest/fetch/api/stores/get-stores-items.md): The expected body payload change between the items endpoint and the stores items endpoint (this) is best described though the following examples. Note that by using this endpoint it will bring only the items that are available to this store and only include this store in the expanded stores section of the item. /api/v2/items? Expand = Stores + filter = lastUpdated >= 2023 - 10 - 30T17:12:12.009Z json [ { "id": "35542435-cf86-11eb-b6e8-8cae4ce6cd26", "description": "tesssst", "posDescription1": "tesssst", "posDescription2": null, "sku": "000000000471", "noCount": false, "shippingWeight": 0.0, "shippingHeight": 0.0, "shippingWidth": 0.0, "shippingLength": 0.0, "uom": null, "childCount": 1.0, "childUsage": 100.0, "upc": [], "active": true, "lastUpdated": "2023-10-30T17:12:12.009Z", "dimension1": null, "dimension2": null, "dimension3": null, "dimension4": null, "dimension5": null, "dimension6": null, "dimension7": null, "dimension8": null, "dimension9": null, "dimension10": null, "level": { "id": "07ab7a19-a9ea-11e3-9931-002590a52022", "code": "00010", "description": "RESTAURANT" }, "level1": { "id": "07ab7a19-a9ea-11e3-9931-002590a52022", "code": "00010", "description": "RESTAURANT" }, "level2": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "level3": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "level4": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "parentItem": null, "recipe": null, "matrix": null, "webProperties": null, "stores": [ { "id": "140e0635-b934-11e3-be42-002590a52022", "bin": null, "reorderPoint": 0.0, "parLevel": 0.0, "tariffCode": null, "description": "Mordor", "code": "1", "revenueCenterNumber": "1", "onHand": 0.0, "retailPrice1": 0.0, "retailPrice2": 0.0, "retailPrice3": 0.0, "retailPrice4": 0.0, "retailPrice5": 0.0, "retailPrice6": 0.0, "retailPrice7": 0.0, "retailPrice8": 0.0, "retailPrice9": 0.0, "retailPrice10": 0.0, "flags": [], "interfaces": { "AccountingGroup": "100", "COGS": "Food", "MicrosClass": "101", "MicrosCondimentsAllowed": "1001", "MicrosFamily": "301", "MicrosItemGroup": "101", "MicrosLevelClass": "999", "MicrosMajor": "101", "MicrosNLUGroup": "10", "MicrosPrintClass": "101", "Publish": "1", "RevenueCenter": "1", "StartingNumber": "950001", "GenericCodeA": "", "GenericCodeB": "", "GenericCodeC": "", "GenericCodeD": "", "GenericCodeE": "", "GenericCodeF": "", "GenericCodeG": "", "GenericLevelA": "", "GenericLevelB": "", "GenericLevelC": "", "ItemNumber": "" } } ], }, { "id": "c81f9a9f-985e-11eb-b6e6-d89c672bbc04", "bin": null, "reorderPoint": 0.0, "parLevel": 0.0, "tariffCode": null, "description": "The Shire", "code": "11", "revenueCenterNumber": "1", "onHand": 0.0, "retailPrice1": 0.0, "retailPrice2": 0.0, "retailPrice3": 0.0, "retailPrice4": 0.0, "retailPrice5": 0.0, "retailPrice6": 0.0, "retailPrice7": 0.0, "retailPrice8": 0.0, "retailPrice9": 0.0, "retailPrice10": 0.0, "flags": [], "interfaces": { "AccountingGroup": "", "GenericCodeA": "", "GenericCodeB": "", "GenericCodeC": "", "GenericCodeD": "", "GenericCodeE": "", "GenericCodeF": "", "GenericCodeG": "", "GenericLevelA": "", "GenericLevelB": "", "GenericLevelC": "", "ItemNumber": "", "Publish": "" }, } ] pulling a single store at a time /api/v2/stores/c81f9a9f-985e-11eb-b6e6-d89c672bbc04/items?Expand=Stores+filter=lastUpdated>=2023-10-30T17:12:12.009Z json [ { "id": "35542435-cf86-11eb-b6e8-8cae4ce6cd26", "description": "tesssst", "posDescription1": "tesssst", "posDescription2": null, "sku": "000000000471", "noCount": false, "shippingWeight": 0, "shippingHeight": 0, "shippingWidth": 0, "shippingLength": 0, "uom": null, "childCount": 1, "childUsage": 100, "upc": [], "active": true, "lastUpdated": "2023-10-30T17:12:12.009Z", "dimension1": null, "dimension2": null, "dimension3": null, "dimension4": null, "dimension5": null, "dimension6": null, "dimension7": null, "dimension8": null, "dimension9": null, "dimension10": null, "level": { "id": "07ab7a19-a9ea-11e3-9931-002590a52022", "code": "00010", "description": "RESTAURANT" }, "level1": { "id": "07ab7a19-a9ea-11e3-9931-002590a52022", "code": "00010", "description": "RESTAURANT" }, "level2": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "level3": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "level4": { "id": "00000000-0000-0000-0000-000000000000", "code": "", "description": "" }, "parentItem": null, "recipe": null, "matrix": null, "webProperties": null, "stores": [ { "id": "c81f9a9f-985e-11eb-b6e6-d89c672bbc04", "bin": null, "reorderPoint": 0, "parLevel": 0, "tariffCode": null, "description": "The Shire", "code": "11", "revenueCenterNumber": "1", "onHand": 0, "retailPrice1": 0, "retailPrice2": 0, "retailPrice3": 0, "retailPrice4": 0, "retailPrice5": 0, "retailPrice6": 0, "retailPrice7": 0, "retailPrice8": 0, "retailPrice9": 0, "retailPrice10": 0, "flags": [], "interfaces": { "AccountingGroup": "", "GenericCodeA": "", "GenericCodeB": "", "GenericCodeC": "", "GenericCodeD": "", "GenericCodeE": "", "GenericCodeF": "", "GenericCodeG": "", "GenericLevelA": "", "GenericLevelB": "", "GenericLevelC": "", "ItemNumber": "", "Publish": "" }, } ], "vendors": [], "images": [], "shortDescription": null, "isEvergreen": null, "style": null, "expirationDays": null, "reference": null, "attributes": null } ] ### Gets a Store's ThirdPartyCodes - [GET /stores/{id}/interfaces/ThirdPartyCodes](https://developer.yellowdogsoftware.com/rest/fetch/api/stores/get-stores-interfaces.md) ## ThirdPartyCodes Additional configuration options that control item, store or level behavior with third-party integrations ### Gets all Third Party Codes - [GET /interfaces/thirdPartyCodes](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/op-interfaces-thirdpartycodes.md) ### Creates Third Party Codes - [POST /interfaces/thirdPartyCodes](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/post-interfaces-thirdpartycodes.md): ##### About Third-Party Interface Codes Third-party interface codes and enumerated types explained To make use of third-party interface codes, one needs to be familiar with the computer programming concept of enumerated types. In general, an enumerated type consists of a type name and a list of possible values. For example, we could define "StorageTemperature" as an enumerated type with three possible values: "RoomTemp", "Refrigerated", "Frozen". It is often useful to define a data field with an enumerated type in order to convey what values are supported and restrict the data to those values. A pulldown menu that allows a single selection is a user interface often used to fill a data field that has been defined with an enumerated type. Note that the possible values that belong to an enumerated type are often called enumerated values. When defining an enumerated type, you must ordinarily give it a and a list of enumerated values which each have a name representing a value. The POST /interfaces/thirdpartycodes endpoint allows a developer to define their own interface codes to serve as enumerated values. Each one is associated with a specified enumerated type. The developer defines the following properties: - The interface code will belong to an enumerated type specified by the "type" property. - A "code" property defines the enumerated value that this interface code will represent. - A "description" property allows an explanatory comment to be attached to each interface code. - The interface code is scoped to a store specified by the "store.id" property. If a new interface code is defined with a "type" name that has not yet been used in the scope of the specified store, a new enumerated type will be created. Interface codes are simply enumerated values that get grouped into enumerated types where the "type" and "store.id" properties happen to match. Annotating items with third-party interface codes A software developer integrating a POS or other system with a Yellow Dog inventory database may find it necessary to annotate inventory items with their own third-party interface codes. For example, they may want to be able to associate particular items with specific menus on a POS terminal or tax categories. They may also need to a way to know which items are relevant to the integration and which items should be ignored. The use of third-party interface codes to perform this annotation is a multi-step process: - First, the developer designs enumerated types name-spaced to their integration for the annotations they care about. - Second, they use the POST /interfaces/thirdpartycodes endpoint to define corresponding "type" and "code" properties. - Third, instructions are provided to customers regarding when and how to annotate items with the specific third-party codes. - Fourth, customers or support staff use pulldown menus in the "Interfaces" tab of various YDInv.exe to apply annotations. Note that name-spacing need only be applied to the "type" property. If the name of the integrated product is "ACME" and the purpose of the enumerated type is a tax category, an appropriately name-spaced "type" property would be "ACME_TaxCategory" with an underscore character separating the name-space from the purpose name. The instructions for annotating items will usually not expect items to be individually annotated with third-party interface codes. The codes will most often be applied to a level category, such as alcoholic beverages, so that all items belonging to that category will inherit a specified interface code. Default codes can also be specified for all items in a store and be overridden by individually assigning a code to an item. Defining a none-of-the-above value When designing a list of enumerated values for a third-party code type that will be used to annotate items, it is important to ask whether all possible cases have been covered. It is often the case that some kind of none-of-the-above value needs to be included to support items where the category itself is not relevant. Consider ___Example A___, which is used to specify a tax category. In addition to county and state tax categories, an untaxed category is defined as a catch-all for items where taxation is not relevant. In YDInv.exe, there is an inherent option to leave a third-party code type as "unset", meaning that none of the available values is chosen for that enumerated type. This cannot be relied upon to serve as a none-of-the-above value because it does not provide a way to override a default setting inherited from a level category or store. In order to support a none-of-the-above selection, there has to be an explicit value that represents it. This is true even if it is interpreted as having the same effect as leaving the third-party code type "unset". Populating a POS item map with the special "ItemNumber" type There is a special third-party interface code type called "ItemNumber". It serves as an enumerated type whose values are POS specific item numbers to be populated into a YDInv.exe POS item map which is scoped to a specific store. When using the POST /interfaces/thirdpartycodes endpoint to add POS items to an item map, the usual interface code properties are specified and have the following effects: - "type" -- must be "ItemNumber". - "code" -- specifies a number that the POS uses to uniquely identify the item on its side - "description" -- will become the description field for the item - "store.id" -- applies to the POS item map for the specified store The store wild card It is possible, although rarely useful, to use a wild card value when specifying the "store.id" property. Since this property is a UUID, an all zero value is used to represent a wild card that applies the enumerated type to all stores in the database. For small databases with only a couple of stores that all use the same POS, it may be reasonable to use this wild card. However, when using third-party interface codes to integrate a POS, it rarely makes sense to do things that limit the integration in this way. As soon as a larger customer comes along with separate POS systems for F&B and retail in a database with more than a couple of stores, some operations will become slower than necessary and it will be easy to for customers to make mistakes once enumerated types start showing up in stores where they are not relevant. These factors are likely to prevent an integration from being certified for larger customers. Note that it is easy to accidentally invoke the store wild card by omitting the "store.id" property and leaving the API to imply a null value. Avoid this mistake and only specify the store wild card when faced with the rare good reason to do so. ##### Examples For the examples that follow, select the corresponding sample payload from the pull-down menu in the request pane. Example A: Defining tax categories ___Example A___ defines a new enumerated type called "ACME_TaxCategory". The "ACME_" prefix applies a name-space to associate this enumerated type with the POS integration that defines it. Three enumerated values are added to this enumerated type to represent county, state, and untaxed tax categories. Note that each of the third-party interface codes created to represent these enumerated values are scoped to the same store. It will be the only store that can annotate level data or items with this enumerated type. It may also be the only store that this ACME POS is configured to use. Example B: Defining a modifier flag ___Example B___ defines a new enumerated type called "ACME_ModifierFlag". As in ___Example A___, the name-space prefix and descriptive name are separated by an underscore character. Since this is type is a flag, it defines "true" and "false" enumerated values in the "code" properties. In this case, "true" and "false" are just name strings with no special function other that their descriptive qualities. Alternatively, "enabled" and "disabled" would also be reasonable values for an enumerated type that is serving as a flag. For reasons described above in the section entitled "Defining a none-of-the-above value", it is necessary for any boolean flag type to explicitly define values for both the on and off state such that the off state has the same effect as leaving the value "unset". Example C: Adding to a POS item map In ___Example C___, there is no name-space prefix because the special "ItemNumber" type name is being used to add items to the POS item map of the specified store. This is the only time that a developer should specify an interface code type without a name-space prefix. Note that the section entitled "Defining a none-of-the-above value" does not apply to the special "ItemNumber" type. ### Updates Third Party Codes - [PUT /interfaces/thirdPartyCodes](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/put-interfaces-thirdpartycodes.md) ### Bulk delete Third Party Codes - [DELETE /interfaces/thirdPartyCodes](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/delete-interfaces-thirdpartycodes.md) ### Gets Third Party Code by Id - [GET /interfaces/thirdPartyCodes/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/get-interfaces-thirdpartycodes-byid.md) ### Deleting a Third Party Code - [DELETE /interfaces/thirdPartyCodes/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartycodes/delete-interfaces-thirdpartycodes-byid.md) ## ThirdParty Third Party Mappings with Yellow Dog Inventory ### Upserts Third Party Items (TPItems) in bulk - [POST /third-party/{syncId}/items](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdparty/post-third-party-items.md): This endpoint allows for bulk upserting of TPItems. ### Creating a TPItems The fields that are required to create a TPLocation are type and code ### Updating a TPItems include the query parameter, upsert=true When a validation error occurs, 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. ### Upserts Third Party Locations (TPLocations) in bulk - [POST /third-party/{syncId}/locations](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdparty/post-third-party-locations.md): This endpoint allows for bulk upserting of TPLocations. ### Creating a TPLocations The fields that are required to create a TPLocation are type and code ### Updating a TPLocations include the query parameter, upsert=true When a validation error occurs, the entire request will fail. ## ThirdPartySessions Records that increment or decrement inventory based on customer interactions with a store ### Gets all Third Party Sessions - [GET /thirdPartySessions](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartysessions/get-thirdpartysessions.md) ### Creates Third Party Sessions - [POST /thirdPartySessions](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartysessions/post-thirdpartysessions.md) ### Gets Third Party Session by Id - [GET /thirdPartySessions/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/thirdpartysessions/get-thirdpartysessions-byid.md) ## Transactions Records that increment or decrement inventory based on customer interactions with a store ### Getting all Transactions - [GET /transactions](https://developer.yellowdogsoftware.com/rest/fetch/api/transactions/get-transactions.md): This endpoint allows for pulling of raw transaction information that is stored in the Yellow Dog Database. As this data is considered to be raw and not processed there is not a way to determine directly with certainty what items or recipes had inventory adjustments from this endpoint. Due to the various Point of Sale integrations that may be connected with the database instance, there is not a guarentee that all transactions will match using the criteria represented in the POST /transactions Endpoint documentation. ### Creates or Updates Transactions - [POST /transactions](https://developer.yellowdogsoftware.com/rest/fetch/api/transactions/post-transactions.md): ##### Matching and Processing The transactionNumber field uniquely identifies a transaction. This POST endpoint will record a new transaction if the __transactionNumber__ does not yet exist. If it does exist, it will overwrite the transaction previously submitted with this value. Both cases assume that the request is not blocked by a closeout date. Note that since this endpoint uses POST, not PATCH, a request that refers to an existing __transactionNumber__ will rewrite the entire transaction and any unspecified fields will be set to empty. Use thirdPartyId & thirdPartyLineId to associate lines within a transaction. When inserting a new record, it is highly recommended that you specify __thirdPartyId__ and __thirdPartyLineId__ values to help you update transactions, when necessary, and to assist in troubleshooting. It is considered a best practice to use a __thirdPartyId__ that corresponds to the ID your system uses to uniquely identify the transaction. If not provided, the API will insert default values in these fields for you. The system uses the __thirdPartyId__ to mantain an internal association between a set of lines and the transaction that contains them. When specifying a preexisting __transactionNumber__ to update a previously submitted transaction, the endpoint will first remove any existing transaction line records that match the specified __thirdPartyId__. It will then record the lines provided in the current payload as the only lines associated with this transaction. Match transaction lines to Yellow Dog Items via id, sku, or itemNumber. This endpoint matches transaction lines to Yellow Dog Items by either the __id__, __sku__, or __itemNumber__ field. - line[].item.id - This will match a transaction line immediately to the Yellow Dog Item with the same id. - This is the preferred method for matching Transaction Lines to the appropriate Yellow Dog Item. - line[].sku - This will match a transaction line to the Yellow Dog Item with the same SKU. - line[].itemNumber - This will match a transaction line to the Yellow Dog Item using a Third Party ItemNumber. - This can be performed by using the POS Item Map feature in Yellow Dog. Only one of the three fields are required to have a non-null or non-whitespace value. Processing depends on checkClosed and closeout dates. Only transactions with a __checkClosed__ date later than the current closeout date will be processed. This setting can be found in the Stores Tab of YDInv. Hourly processing matches lines to items. Transactions will be processed on an hourly basis. Each transaction line will be matched to the appropriate Yellow Dog item when processing occurs. For assistance on this matter, please contact your Implementation Guide. ##### Examples For the examples that follow, select the corresponding sample payload from the pull-down menu in the request pane. Example A: Sending a transaction with multiple lines In ___Example A___, there was a sale of a Burger and a bottle of water. The expected total for the transaction with all the lines will have a retail of $17.00. Example B: A transaction with item modifier lines In ___Example B___, there was a sale of a Burger with the additional modifiers for adding cheese and bacon. As part of the inventory processing the use of the modifiers will allow for the processing of the transactions to deduct the 2 cheese and 2 bacon appropriately. In this example the expected total for the transaction with all the lines will have a retail of $23.00. Example C: A transaction with a Check-Wide Discount In ___Example C___, there was a sale of a Burger with the additional modifiers for adding cheese and bacon. There was also a discount set for 20% off the entire check. Notice how the itemDiscount is set for each line of the transaction. This allows for proper setting of the item price. In this example the expected total for the transaction with all the lines will have a retail of $18.40. Examples D&E: Handling of Refunded Return In this example, there was a sale of a Tee Shirt that was then returned with refund the following day. To properly handle the deduction and then increment of inventory for the two actions, there should be two separate transactions sent to the api. Here, ___Example D___ shows the initial sale and ___Example E___ shows the return. Ideally, the transactions should be marked for the appropriate times that they happened at. Notice that in this example the __thirdPartyId__ and __thirdPartyLineId__ are different values between the sale and the refund. Examples F&G: Handling of a Void or a Cancellation In this example, there was a sale of a Tee Shirt that was canceled or voided without a decrement of inventory. This could have been an accidential addition of an item for the transaction. Here, ___Example F___ shows the initial sale and ___Example G___ shows the cancellation. Since this this event is not supposed to impact the inventory onhand, it is appropriate to set the quantity of the existing line to 0 as an update to the original transaction. Notice that in this example the __thirdPartyId__ and __thirdPartyLineId__ are the same values between the sale and the voided line. ### Gets Transactions by Store - [GET /transactions/store/{storeId}](https://developer.yellowdogsoftware.com/rest/fetch/api/transactions/get-transactions-store.md) ### Gets Transaction by ThirdPartyId - [GET /transactions/{thirdPartyId}](https://developer.yellowdogsoftware.com/rest/fetch/api/transactions/get-transactions-byid.md): This endpoint is intended to be used for looking up a specific Transaction record. ## Transfers A record of movement of Items from one Store to another. ### Accepts a Transfer - [PATCH /transfers/{id}/Accept](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/patch-transfers-accept.md): Accepting a Transfer is an indication that the Store on the recieving side of the Item movement has been recieved at the quantities indicated by the accepting quantity. ### Issues a Transfer - [PATCH /transfers/{id}/Issue](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/patch-transfers-issue.md): Issuing a Transfer is an indication that the Store on the sending side of the Item movement has been sent to the Store on the Recieving side. ### Gets Transfers - [GET /transfers](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/get-transfers.md): Example use cases api/v2/transfers?pageNumber=1&pageSize=100&Filter=committed>2024-03-05T06:06:58.529Z&Filter=lastUpdated>2024-03-06&orderBy=committed will get the first page of transfers where the committed date is later than 2024-03-05T06:06:58.529Z AND the lastUpdated date is later than 2024-03-06T00:00:00Z, ordering by the committed date /api/v2/transfers?pageNumber=1&pageSize=100&Filter=committed>2024-03-05T06:06:58.529Z&orderBy=committed will get the first page of transfers where the committed date is later than 2024-03-05T06:06:58.529Z ordering by the committed date. ### Creates a Transfer - [POST /transfers](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/post-transfers.md) ### Add Additional lines to an existing Transfer that has not been committed - [POST /transfers/{id}/lines](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/post-transfers-lines.md) ### Updates existing lines of a given Transfer - [PATCH /transfers/{id}/lines](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/patch-transfers-lines.md) ### Delete existing lines from a Transfer - [DELETE /transfers/{id}/lines](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/delete-transfers-lines.md) ### Gets a Transfer By ID - [GET /transfers/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/get-transfers-byid.md) ### Updates an existing Transfer - [PATCH /transfers/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/transfers/patch-transfers-byid.md) ## Vendors Vendors, Suppliers, Distributors, or Manufacturors that provide Items into the Inventory. ### Getting Vendors - [GET /vendors](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/get-vendors.md) ### Creating new Vendors - [POST /vendors](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/post-vendors.md) ### Updating existing Vendors - [PUT /vendors](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/put-vendors.md): If the stores array is null or empty, then Store associations will not be updated. If you want to set the availability of a store for a given vendor, add elements to the stores field, with the Available value set. ### Getting Vendor by Id - [GET /vendors/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/get-vendors-byid.md) ### Bulk delete Vendors (deprecated) - [DELETE /vendors](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/delete-vendors.md) ### Deleting a Vendor (deprecated) - [DELETE /vendors/{id}](https://developer.yellowdogsoftware.com/rest/fetch/api/vendors/delete-vendors-byid.md)