Catalog Search

Catalog search is used to find items in the API POS system by passing a structured query into it, letting the system process the query, and then pulling the results when 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.

For example, to perform an OData Search, you would first build out the OData request and pass it 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 via the GET Catalog OData Search endpoint when they are available.

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.

Performing a Catalog Search using an OData Request

• 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:
  • 'AccountCredit' - Account Credits
  • 'GiftCard' - Gift Cards
  • 'Retail' - Retail Products

  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.

  
  

  The following site settings are taken into account when searching for Retail products:

  • Retail Products & Inventory will filter out any retail products from the catalog search when disabled.

Searching for service pricing options for a specific class, appointment, or enrollment

• 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 Search For Service Pricing Options endpoint.To use build a search request, you will specify the type of service you are searching for in the “{serviceCategoryType}“ value of the route (Class, Appointment, or Enrollment), as well as the specific ID of that type in the {instanceId} value.

  A search ID will be returned from the POST endpointendpoint, which can then be used in the GET endpoint to return the results when they are available.