# Third Party Codes / Interfaces

*The following explains how POS specific Third Party Codes / Interfaces can be applied to item data.*

Note that in the Fetch API when you post new POS specific properties they are referred to as Third Party Codes,
but when you get those POS specific properties as they are assigned to items they are referred to as Interfaces.
For the Yellow Dog user, they are known as Interfaces.

## Plan Your Required Codes

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.

- This is generally a true/false option named using their company's / POS's name followed by "_Publish",
which would designate to your code whether the item should be pulled into your system or not.
  - For example if your POS's name is Acme, you would name yours "Acme_Publish".
  - If true, you would pull that item into your system.
  - If false or blank/null, you would NOT pull that item into your system.


Think about what other item specific properties your POS needs to know about that may not
be present in a standard field that could be interpreted the same way for all customers.
For each POS specific property that you need to know about, you can define a third party code
/ interface requirement, which is like an annotation for the items.

For example, your POS may need to flag an alcohol purchase so that the terminal
operator knows that they need to ask the patron to present their ID.
Some clients encode this into their level data but they don't all do it the same way.
You can solve this by defining "Contains Alcohol" as a third party code / interface requirement,
again, prepending with your company/POS name, "Acme_Contains Alcohol".

Other commonly used third party code / interface examples are [YourCompany/POSName]_Category ("Acme_Category")
and [YourCompany/POSName]_TaxGroup ("Acme_TaxGroup"),
but it is up to you to determine what is needed for your integration.

Note that these third party codes / interfaces will be set by the Level in Yellow Dog
and inherited by the items assigned to that level.
So even though you will be getting the interface from the item in the API,
third party codes / interfaces are not normally assigned directly to the item in Yellow Dog's UI.

Although some interfaces may be location specific in your system, your code should look to a designated
Primary Store for [YourCompany/POSName]_Publish and other non-location specific interfaces.
This simplifies things in your code but also simplifies things for the customer,
who will be trained to make all items they want published to your system available to the designated Primary Store
for the integration and then will only have to set the interfaces on that store,
as opposed to all stores the item is available to.

## Choose names and defaults for your defined codes

Think of each third party code / interface requirement that you encounter as a drop down menu that can
select from two or more options.
You will need a name for each third party code / interface requirement and for each option it contains.
You must also decide which of these options should serve as a default when no option has been selected.

## POS defines requirements - Client meets them

After the POS determines its item third party code / interface requirements, it uses the
[POST /interfaces/thirdPartyCodes](/rest/fetch/api/thirdpartycodes/post-interfaces-thirdpartycodes)
endpoint to define them at installation time in the Yellow Dog database for a specific client.
The client then works with the Yellow Dog implementation team to map categories of Item
data (Levels) to the appropriate POS defined options for each third party code / interface requirement.

The POS decides which of its third party code / interface requirements must bear an explicit value
for an item to be usable and which can can infer a default value when not specified.
When the integration goes live, the POS periodically checks for updates to item data.
It ignores any items that don't meet explicit requirements and applies default values
where optional third party code / interface are unspecified.

## How to use POST /interfaces/thirdPartyCodes

See the [POST /interfaces/thirdPartyCodes](/rest/fetch/api/thirdpartycodes/post-interfaces-thirdpartycodes)
endpoint documentation for more information about defining POS specific annotations.