MRoute API

The MRoute API returns a merchandised product listing for a merchandising route — a named page or section (for example, a category landing page such as /category/dresses) — rather than results driven by a free-text search query.

The result set for a given route reflects the merchandising configuration set up for your website (boosting, hiding, sorting, filtering, etc.), combined with anything you pass in the request body.

The MRoute API allows scope, aggregations, and range_fields in the request body — see Summary for how these merge with the route's configuration.

API Endpoint

Method: POST

URL: https://<PA_SEARCH_END_POINT>/mroute

Request Header

Name	Value
`Content-Type`	`application/json`

Request Parameters (Body)

Parameter	Type	Required	Default	Description
`route`	String	Yes		Merchandising route path configured in the PA webapp.
`website_id`	String	Yes		Client unique website ID provided by PA.
`client`	String	Yes		Unique client shortcode provided by PA.
`start`	Integer	No	`0`	Offset from the first result to fetch (pagination).
`size`	Integer	No	`20`	Maximum number of results per page.
`scope`	Object	No	`{}`	Filter criteria. Keys are field names, values are filter values or range objects. See Summary for value formats and how this merges with the route's configured scope.
`aggregations`	Array of String	No	`null`	List of fields to aggregate for faceted search. See Summary for how this interacts with the merchandising configuration.
`range_fields`	Array of String	No	`null`	List of numeric fields for range filtering. See Summary for how this interacts with the merchandising configuration.
`sort_fields`	Array of `{field: Sort}`	No	`[]`	Sort specifications. Each object has field name as key with `order` and `type` properties. Multiple entries apply sort priority in order.
`selected_fields`	Array of String	No	`null`	Restrict the response to only these fields. See Summary for how this affects `attributes`.
`include_oos`	Boolean	No	`true`	Whether to include out-of-stock items in results.

Example Request Payload

{
  "route": "/category/dresses",
  "website_id": "bd03068c-a587-eb11-aac4-0210d78x2f3e",
  "client": "csc",
  "start": 0,
  "size": 20,
  "scope": {
    "brand": ["Kansas"],
    "product_category": ["Furniture > Category1 > Subcategory1", "Furniture > Category2 > Subcategory2"],
    "sale_price": { "min": 10 }
  },
  "aggregations": ["brand", "product_category", "sale_price"],
  "range_fields": ["sale_price"],
  "sort_fields": [
    { "org_price": { "order": "asc", "type": "number" } }
  ],
  "include_oos": true
}

Response Payload

{
  "type": 1,
  "code": 0,
  "payload": {
    "total_results": 274,
    "next_cursor": null,
    "aggregations": {
      "brand": [
        { "doc_count": 260, "key": "Kansas" },
        { "doc_count": 14, "key": "Other Brand" }
      ],
      "product_category": [
        { "doc_count": 260, "key": "Furniture > Category1 > Subcategory1" },
        { "doc_count": 14, "key": "Furniture > Category2 > Subcategory2" }
      ],
      "sale_price": {
        "count": 16,
        "min": 2,
        "max": 24.99,
        "avg": 6.08,
        "sum": 97.34
      }
    },
    "result": [
      {
        "item_group_id": "250433",
        "refId": "REF-12188",
        "sku_id": "12188",
        "availability": -1,
        "title": "Sample item",
        "image_link": "https://www.testlink.au/",
        "link": "https://www.testimagelink.au",
        "website_logo": "https://www.samplelogo.au",
        "product_category_id": 465,
        "object_types": ["shelf", "cupboard"],
        "personalized": false,
        "attributes": {
          "org_price": 449.0,
          "sale_price": 319.0,
          "brand": "Kansas",
          "color": "white",
          "product_type": "Furniture > Category1 > Subcategory1",
          "product_category": "Furniture > Category1 > Subcategory1"
        },
        "score": 1.0
      },
      {
        "item_group_id": "250434",
        "refId": "REF-12189",
        "sku_id": "12189",
        "availability": -1,
        "title": "Another sample item",
        "image_link": "https://www.testlink2.au/",
        "link": "https://www.testimagelink2.au",
        "website_logo": "https://www.samplelogo.au",
        "product_category_id": 466,
        "object_types": ["chair"],
        "personalized": false,
        "attributes": {
          "org_price": 199.0,
          "sale_price": 149.0,
          "brand": "Kansas",
          "color": "black",
          "product_type": "Furniture > Category2 > Subcategory2",
          "product_category": "Furniture > Category2 > Subcategory2"
        },
        "score": 0.85
      }
    ]
  }
}

Response Fields

Field	Type	Description
`type`	Integer	Determines the status of the request; `1` = success, `-1` = failed.
`code`	Integer	Response code (always `0`).
`payload.total_results`	Integer	Total number of matching products.
`payload.next_cursor`	Object \| null	Pagination cursor for the next page.
`payload.aggregations`	Object	Keyed by aggregated field. Categorical fields return `[{doc_count, key}]` buckets; fields also listed in `range_fields` return a stats object (`count`, `min`, `max`, `avg`, `sum`).
`payload.result`	Object Array	List of matched products — see Product Object.

Product Object

Field	Type	Description
`image_link`	String	Product image URL.
`link`	String	Product page URL.
`item_group_id`	String	Product group identifier.
`sku_id`	String	Product SKU identifier.
`title`	String	Product title.
`score`	Float	Relevance/ranking score, 0 to 1.
`website_logo`	String	Website logo URL.
`product_category_id`	Integer	Product category identifier.
`object_types`	Array of String	Object type tags for the product.
`personalized`	Boolean	Whether this result was personalized.
`availability`	`0` \| `-1`	`0` = out of stock, `-1` = in stock.
`refId`	String \| null	Product reference identifier.
`attributes`	Object	Additional product attributes (`org_price`, `sale_price`, `brand`, `product_type`, `product_category`, etc).

No matching route: if route doesn't resolve to a configured merchandising route for your account, the API returns 200 OK with an empty result set:

{
  "type": 1,
  "code": 0,
  "payload": { "total_results": 0, "results": [] }
}

Errors

Status	When	Body
`422 Unprocessable Entity`	Request body fails validation (e.g. missing `route`/`website_id`/`client`, or a field has the wrong type).	Standard validation error body listing the invalid fields.
`429 Too Many Requests`	Rate limit (10 requests / 2s per IP) exceeded.	Rate-limit error body.
`500 Internal Server Error`	Server error while processing the request.	`{"type": -1, "code": 0, "message": "Failed to process mroute request: <error>", "payload": {"statusCode": 500, "Content": ""}}`

Summary

The MRoute API returns merchandised results for a configured route using field-value matching (via scope); it does not accept a free-text search query.
Out-of-stock products are included by default; set include_oos to false to exclude them.
Supports scope filters, sort_fields, and pagination for narrowing, ordering, and paging results within a route.
In scope, text fields accept a string or a list of strings (matches any of the specified values), numeric fields accept a {min, max} range, and different fields are AND-ed together.
For scope, the route's configured value takes priority on any field set in both places (fields set in only one are merged); for aggregations and range_fields, the request body's value fully replaces the merchandising configuration instead of merging field-by-field.
To get attribute data with selected_fields, list the specific fields you need (e.g. brand, sale_price) — they'll come back as flat top-level fields, not nested inside attributes.

API Endpoint​

Request Header​

Request Parameters (Body)​

Example Request Payload​

Response Payload​

Response Fields​

Product Object​

Errors​

Summary​