# CF API documentation: stores vs related_stores

`store` and `related_stores` are two fields in the response payload from the `/search` endpoint, from Adeptmind. In this document we briefly explain the bahavior/expectations regarding these two fields.

### Overview
- stores:
- when the search is likely to be targeting one or more specific stores, Adeptmind will put targeted stores under `stores` field.
- related_stores:
- for stores that the returned products are sold in, they are put into `related_stores` field
- additionally, if Adeptmind has additional knowlege that similar products can be sold in some other stores, those stores will also be put into `related_stores` field
- if a store appears in `stores` field, it will be removed from `related_stores` field

### More Details
Assuming Adeptind has three stores in its catalog, "Zara", Nike" and "FootLocker", all three selling running shoes.
- "Zara":
- Zara is both a store, and a brand
- as a brand, the brand is sold exclusively in-store, you cannot find "Zara" products in other stores
- "Nike"
- Nike is both a store, and a brand
- as a brand, the brand is sold in multiple stores, including itself
- "FootLocker":
- FootLocker is a store
- as a store, footlocker sells "Nike" products

- 1, Query: "running shoes"
- stores: []
- related_stores: [FootLocker, Zara, Nike]
- 2, Query: "running shoes", Guided-Discovery-Pill: "Nike"
- stores: [Nike]
- related_stores: [SportsChek]
- Guided-D will trigger a BRAND search, products from both Nike and SportsChek will be returned. Both stores will be populated in `related_stores`, Nike will be promoted to `stores` because of "BRAND:Nike" segment
- 3a, Query: "running shoes", Filter: "BRAND:Nike"
- stores: [Nike]
- related_stores: [SportsChek]
- similar to 2.
- 3b, Query: "running shoes", Filter: "BRAND:Zara" and "BRAND: Nike"
- stores: []
- related_stores: [Zara, Nike, SportsChek]
- similar to 2 and 3a, except promotion will not happen when multiple matches are found on BRAND segments
- 4, Query: "running shoes", Filter: "STORE:Nike"
- stores: [Nike]
- related_stores: []
- 5, Query: "nike running shoes"
- stores: [Nike]
- related_stores" [SportsChek]

### Action items as of 20200207, if we agree with everything above.
- for bug https://cadillacfairview.atlassian.net/browse/CFB-860
- need to implement promotion
- need to improve related_stores quality, this is a bug reported by Elza
- need to figure out if there are any more problems with non-shop queries (query: "specialty food")

- for bug https://cadillacfairview.atlassian.net/browse/CFB-897
- need to make sure our `related_stores` generation logic is correct

### implementation checks
- make sure `related_stores` is populated exactly from list of returned products
- make sure there is no collision between `related_stores` and `stores`
- promotion needs to be implemented