Catalog Search

Introduction

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.

How It Works

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 (POST) to build the request and receive a token, that you then use to hit another endpoint (GET) to retrieve the result set.

For example, to use the POST Sales/{subscriberId}/Catalog/Search, you would build out the request and pass it to the endpoint. The method takes the 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 request is executed the results will be available to be accessed by passing the token into the GET Sales/{subscriberId}/Catalog/Search/{itemsRequestId} in the {itemsRequestId} parameter.

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.

How To Use Catalog

This section describes how to do a catalog search for items. If you'd like to search for series that can pay for Appointments, Classes, or Enrollments, please see Catalog Search for Series.

Catalog searching was built off of the OData query model for building a request to retrieve results. This model includes any filtering, ordering, and result count (pagination) required for the consumer. That is, you pass all the filtering, ordering, and result counts you want to receive to the endpoint.

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
  • 'ServicePricingOption' - Service Pricing Options
  • 'Retail' - Retail Products
To add multiple options to the OData query string, prepend each additional option with "&" and then the option and value. For example, if I wanted to add an order by and skip and top options to my query it would look like: 
?$filter=ItemType eq 'GiftCard'&$orderby=ItemId&$top=10&$skip=20


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:

  • Hide Out Of Stock Products will filter out any products that are out of stock when setting is enabled.
  • Show # In Stock To Public will exclude the inventory amount from the Retail product template in the search results when setting is disabled.
  • Sell Your Own Products Online will exclude any and all retail items from the catalog search when setting is disabled.
  • Online Retail Store will exclude any and all retail items from the catalog search when setting is disabled.

Example for search.

  • Send Request With Query
    • Request
    • Response 
      • {"ItemsRequestId": “12ab3c45-d6e7-8f9g-01h2-3i4k5lmn6789",    "ExpiresIn": 900}
  • Send Request For Results
    • Request
    • Response

Current Limitations

  • November 11, 2014

    • Gift Card Image URL sizes are currently using the same (original) size image. There are plans to expand this into multiple sizes in the future.

Miscellaneous

CatalogItem

The CatalogItem is the item information provided from the Catalog Search request.

It is intended to include all details necessary to implement a UI simply based on the details of the item.

The details include, but are not limited to:

  • the item type (ex.: gift card, retail, etc.)
  • any options available (ex.: gift card images, sizes, etc.)
  • item price(s)
  • values (gift card amount)
  • any rules regarding the item (ex.: is the amount editable or not),
  • what payments methods are accepted for that item
  • what fields are required or not for the item (ex.: gift card messages, sender, delivery date, etc.)

See the CatalogItem object specification for more details.

OData

OData is a standardized way to provide CRUD operations to .NET-based APIs, and is how our system pulls the correct data from data storage based on the API request.

The requests are based on OData URI Conventions.

For example: 

?$filter=ItemType eq 'GiftCard'&$orderby=ItemId&$top=10&$skip=20

This is telling the request to only show results with an ItemType of "GiftCard", to order the results by the ItemId, to skip the first 20 results, and pull the next 10 (results 20 through 30).

Helpful Links