The Catalog Search is used to find items that can be purchased using the POS API. Using the search requires two steps. First, you must POST an OData request to construct a feed (a collection of results). After requesting a feed you must GET the results, polling until they are ready.
The structure was designed to work asynchronously to help manage system load, and be able to provide results faster via caching and other methods. To use the search, you will initially hit an endpoint (HTTP POST) to build the request and receive a token that you then use to hit another endpoint (HTTP GET) to retrieve the result set.
To perform an OData Search, you would first build out the OData request and pass it to the
POST Catalog Feed V2 OData
.
To perform a search based on a schedule item use POST Catalog Feed V2 Schedule Item .
All endpoints that create feeds will return a reference to the feed.
This reference is used in the following endpoint:
GET Catalog Feed V2
. It is expected that consumers of this API poll on the above endpoint until the feed is ready to be returned.
Polling Recommendations:
In initial wait time of 450ms is recommended with an increasing back off policy for subsequent polls.
We recommend a polling back off structure of: 250ms, 250ms, 350ms, 350ms, 350ms
Polling 5 times while the feed is still pending will cause it to be cancelled.
Check out event sourcing and cqrs to learn more about these topics.
Any masking, user permissions, or other restrictions based on the user context (client, staff, owner, etc.) will be taken into account when the results are ready. For example, if a staff user is requesting a list of items but they do not have the permission to view gift cards, any gift card items will be removed from the results.
To perform a catalog search using an OData request, you pass an OData request to the POST Catalog OData Search endpoint . This method takes the search request, puts it in the queue to be executed, and returns a response with a token to be able to retrieve the results when they are available.
Once the search request is executed the results will be available to be accessed by passing the token returned from the POST Catalog OData Search endpoint into the GET Catalog OData Search endpoint in the {itemsRequestId} parameter.
To specify the type of items you want to search for, specify ItemType in the OData filter
?$filter=ItemType eq 'GiftCard'Supported types of items are:
Special characters need to be encoded when using an OData request.
For example, if you are searching for an item with a name of "Yoga Mat - Blue & Gold",
you would need to encode the "&" as "%26" making your filter look like: "Name eq 'Yoga Mat - Blue %26 Gold'".
See MSDN's Special Characters page for more information.
Though similar to the Catalog OData Search functionality, searching for service pricing options that can pay for a class, appointment, or enrollment needs different information in order to perform the search. As such, separate endpoints were developed to facilitate this
The search is used to find service pricing options specific to a class, appointment, or enrollment which is specified in the POST Catalog Feed V2 Schedule Item .To use build a search request, you will specify the type of service you are searching for (Class, Appointment, or Enrollment), as well as the specific ID of that type in the value.
After polling GET Catalog Feed V2, you will receive a list of catalog items. See CatalogItem and CatalogPackage for more details.