Category API

get

https://{siteId}.a.athoscommerce.net/v1/category

Returns category page results, filters, sort options, pagination, active filters (if active), configured merchandising data (if triggered), and spell correction information to build a category results page. See Category Result Pages to see where this endpoint is used. This endpoint should be used specifically for category page requests instead of the Search API endpoint.

Query Params

string

length ≤ 256

Refinement query used primarily for category searches. This will allow you to search within a specific category or categories. Will support up to 256 characters.

filter

object

Filters the array of results. Filter parameter is used when a customer applies a filter in the UI.

Parameter names should be "filter.[field]", value is case sensitive.

Examples:

filter.color=blue
filter.size=Large

If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field.

Examples:

filter.price.low=2
filter.price.high=120

bgfilter

object

Functions the same as the filter parameter except it is used to filter initial results on pages like Category or Collection pages, or can also be used to filter initial results for all pages or specific pages of the site. This parameter should not be usable in the UI by a customer, see the filter parameter for customer interactions to filter results.

Parameter names should be "bgfilter.[field]", value is case sensitive.

Examples:

bgfilter.collection_handle=new-arrivals
bgfilter.is_published=1

Examples:

filter.price.low=2
filter.price.high=120

sort

object

Used to sort returned results.

Parameter names should be "sort.[field]=[asc/desc]"

Examples:

sort.price=asc
sort.is_bestseller=desc

userId

string

required

If the cookie "athosUserId" is currently set, use the value as the userId value.

If it doesn't exist yet, generate a new ID and store it in the "athosUserId" cookie.

sessionId

string

required

If the cookie "athosSessionIdNamespace" is currently set, use the value as the sessionId value.

If it doesn't exist yet, generate a new ID and store it in the "athosSessionIdNamespace" cookie.

pageLoadId

string

required

Create a new ID for this parameter on every page load. If using a headless build create a new ID for this parameter on every URL route change.

If it doesn't exist yet, generate a new ID.

domain

string

required

The full URL of the current page.

resultsPerPage

integer

Defaults to 24

This will allow you to override the number of results per page that are returned in the Search API response in the results array.

page

integer

Defaults to 1

The page of results to be loaded.

redirectResponse

string

enum

Defaults to minimal

Will change how redirects behave in the API response.

direct - will return a 302 and redirect a shopper to the returned URL within merchandising.redirect in the response. Direct is best for API integrations as it is the most performant.
minimal - returns a partial API response without results data. Redirect URL will be returned in the merchandising object. If redirectResponse is not passed the default behavior is minimal.
full - returns the full API response with results data. Redirect URL will be returned in the merchandising object.

Allowed:

landing-page

string

Will allow the API to search the database for products that are a part of a configured landing page campaign.

Landing page campaign example: landing-page=black-friday

tag

string

Will allow our API to search the database for products that are a part of a configured segmented merchandising campaign. To trigger a segmented merchandising campaign the value must follow this format, tag=merch.segment/[your-tag-here].

Segmented Merchandising campaign example: tag=merch.segment/logged-in-black-friday

includedFacets

string

Will allow you to specify specific facets you would like returned in the API response. The specified value passed must be the name of the facet field for it to be included. If the parameter is included, but the value is blank, facets will not be returned in the response.

excludedFacets

string

Will allow you to remove a specified facet from the facets array returned in the API response. The specified value passed must be the name of the facet field for removal to function as expected.

disableInlineBanners

string

Will disable inline banners from being returned in the API response.

lastViewed

string

Comma seperated list of product SKUs or UIDs that the customer has recently viewed. The most recently viewed product SKU or UID being at the front of the string of product SKUs or UIDs passed. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

cart

string

Comma seperated list of product SKUs or UIDs that are in the current customers cart. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

shopper

string

ID of current logged-in shopper from your platform, this is required for personalization features. If the shopper is anonymous this should be omitted. To learn more about personalized search, please refer to this link for more information.

test

boolean

Defaults to false

Specify that this event is a test event - this prevents our tracking system from processing the event as a real user interaction.

Headers

HTTP_X_FORWARDED_FOR

string

This header is required only for accounts that are making API requests within their server (server-side integration). \n\nIn order for requests to be properly handled pass the active customer's IP address to Athos as the value for this header.

Responses

302

This status code will be returned when a query value passed in the API request matches a configured redirect in the Athos Management Console and the query parameter redirectResponse=direct is in use.

400

Bad Request

403

403 Request generated a response that was too large

404

404 Not Found

405

405 Method Not Allowed

429

429 Too Many Requests

500

Internal Server Error

502

Bad Gateway

503

This status code will be returned when the request hits a timeout of 5 seconds.

200OK