Runtime_CategoryProductList_Load_Query#
Description#
This function returns a list of products assigned to a specific category. This is a runtime function intended to be called client side to product data for a specific category. Because this is a runtime (public) function no API key is required. This function has ondemandcolumns to optionally retrieve inventory, attribute and options, discounts, sale price, and default category. In addition, there are optional filters to return images including dynamically requesting image sizes that may not exist yet.
Request Parameters#
Parameter |
Type | Description |
|---|---|---|
count |
Number | Maximum lines of data allowed to be returned in the response. This limit is used to prevent excessive amounts of data return |
filter |
String | A string for filtering returned data |
offset |
Number | Used with the Count parameter for paginating results of large datasets. Default 0 is no offset. |
sort |
String | The order for sorting returned data |
session_type |
String | This will always have a hard-coded value of “runtime.” This tells Miva, no authentication is needed for the API call. |
Session_ID |
String | Passing the Session_ID in the request will allow any customer-specific discounts get applied. |
Category_IDedit_CategoryCategory_login |
Number String String |
The category id The category name The category name |
On Demand Columns#
| Name | Description |
|---|---|
descrip |
Full HTML product description |
inventory |
Inventory count and inventory settings |
attributes |
Product attributes and options |
sale_price |
Discounted sale price for the product. When sale_price is requested, the price standard field will be overwritten with the sale price value. |
discounts |
Any discounts applied to the product creating the sale_price |
category |
Canonical category for each product. This is determined, first by the canonical category, if specified, and second, the first category to which the product is assigned. |
facets |
Loads the available facets for the result set |
subscriptionsettings |
Loads subscription settings for the products returned |
subscriptionterms |
Loads subscription terms for the products returned |
CustomField_Values:* |
See custom field usage here: List Load Query Overview |
Other Custom Filters#
| Name | Description |
|---|---|
imagetypes |
This filter may be specified more than once. Each instance of the filter may request different sizes. If “sizes” is not specified, only the original image is returned. Requested sizes that do not exist will be generated. |
images |
This filter returns all of the images assigned to a product, regardless of image type. Any sizes passed will be generated/returned for all images. |
runtime_search |
Performs a runtime search against the products (same as if the customer used the search box on the site). Only the columns included in the response are searchable. Inventory and attributes are not searched. |
Supported Sort Columns#
One of these values would be passed in the sort request parameter to have the results sorted by that column.
Column |
Description |
|---|---|
relevance |
Sort by relevance |
customfield/customfield_desc |
Sort by custom field (descending) |
disp_order/disp_order_desc |
Sort by display order (descending) |
newest |
Sort by newest |
oldest |
Sort by oldest |
updated |
Sort by last updated |
code_asc |
Sort by code (ascending) |
code_desc |
Sort by code (descending) |
name_asc |
Sort by name (ascending) |
name_desc |
Sort by name (descending) |
price_asc |
Sort by price (ascending) |
price_desc |
Sort by price (descending) |
bestsellers |
Sort by bestsellers |
Response Parameters#
Parameter |
Type | Description |
|---|---|---|
total_count |
Number | total_count is the total number of records that match your search criteria. Note: this is not always the total products returned. Based on the Count and Offset parameters passed, the number of records returned could be different than the total_count. |
start_offset |
Number | Number of the starting offset number of products to return. Used in conjunction with the Count parameter for paginating results of large datasets. |
id |
Number | Product Id |
code |
String | Miva Product Code (unique) |
Sku |
String | Product SKU |
image |
String | This field is depreciated and is supported for legacy purposes. Relative Path to the product fullsize image. |
thumbnail |
String | This field is depreciated and is supported for legacy purposes. Relative Path to the product thumbnail image. |
disp_order |
Number | Product Display Order |
output_disp_order |
Number | Output Product Display Order |
dt_created |
Object | Date Time Stamp the product was created |
dt_Updated |
Object | Date Time Stamp the product was last updated |
weight |
Number | Product Weight |
taxable |
Boolean | true/false flag if the product is taxable |
price |
Number | Product Price |
formatted_price |
String | Currency-Formatted Product Price |
retail |
Number | Retail price before any discounts have been applied |
formatted_retail |
String | Currency-Formatted Retail Price |
base_price |
Number | Includes any legacy price group discounts but does not reflect sales, coupons or discounts applied in the basket |
formatted_base_price |
String | Includes any legacy price group discounts but does not reflect sales, coupons or discounts applied in the basket |
quantity |
Number | Quantity |
url |
String | Canonical URL to the product |
descrip |
String | Only output if “descrip” is passed as an ondemandcolumn. Full HTML description. |
attributes |
Object | Attributes |
sale_price |
Number | Sale Price with discounts applied. If you want customer-specific prices the Sesssion_ID should also be passed in the request |
inv_active |
Boolean | Boolean flag for Inventory Active for this product |
inv_level |
String | One of In Stock, Low Stock, Out of Stock |
inv_available |
Number | Inventory Available |
inv_available |
Number | Inventory Available. This is the instock amount - threshold you have set for out of stock level (default is 0) |
inv_instock |
Number | Inventory In Stock |
inv_short |
String | Inventory Short Message |
inv_long |
String | Inventory Long Message |
page |
Object | Page Template |
category |
String | Canonical Category Product is Assigned To |
discounts |
Object | Discounts |
images |
Object | Images |
imagetypes |
Object | Request Images By Image Types. Contains child objects with the image type name. |
discounts |
Object | Discounts |
CustomField_Values:* |
Object | See custom field usage here: List Load Query Overview |
| #customfield_values) |
dt_created Object#
Parameter |
Type | Description |
|---|---|---|
time_t |
Unix Timestamp | Unix Timestamp for date created |
year |
Number | Year |
month |
Number | Month |
day |
Number | Day |
hour |
Number | Hour |
minute |
Number | Minute |
second |
Number | Second |
timezone |
Number | Offset from UTC |
dt_Updated Object#
Parameter |
Type | Description |
|---|---|---|
time_t |
Unix Timestamp | Unix Timestamp for date updated |
year |
Number | Year |
month |
Number | Month |
day |
Number | Day |
hour |
Number | Hour |
minute |
Number | Minute |
second |
Number | Second |
timezone |
Number | Offset from UTC |
attributes Object#
Parameter |
Type | Description |
|---|---|---|
id |
Number | Attribute ID |
product_id |
Number | ID of product attribute is assigned to |
default_id |
Number | ID of default attribute option |
disp_order |
Number | Display Order. Used in sorting attributes. |
code |
String | Attribute Code |
type |
String | One of the following types: radio, checkbox, text, memo, swatch, swatch-select |
attemp_id |
Number | Will contain the id of the attribute id reference, otherwise 0 |
prompt |
String | Attribute Text displayed to customer during runtime |
price |
Number | Attribute Price |
formatted_price |
String | Currency Formatted Attribute Price |
weight |
Number | Attribute Weight |
required |
Boolean | Flag if the Attribute is Required |
inventory |
Boolean | Flag if Inventory is being tracked on this attribute. Required when using Inventory Variants. |
image |
String | Attribute Image - Relative path to image file. |
options |
Object | Options |
options Object#
Parameter |
Type | Description |
|---|---|---|
id |
Number | Option ID |
product_id |
Number | ID of product attribute is assigned to |
attr_id |
Number | ID of attribute option is assigned to |
disp_order |
Number | Display Order. Used in sorting options. |
code |
String | Option Code |
prompt |
String | Option Text displayed to customer during runtime |
price |
Number | Option Price |
formatted_price |
String | Currency Formatted Option Price |
weight |
Number | Option Weight |
image |
String | Option Image - Relative path to image file. |
page Object#
Parameter |
Type | Description |
|---|---|---|
id |
Number | Page Id for template controlling product (default template is PROD) |
code |
String | Page Code for template controlling product. (default template is PROD) |
title |
String | Title of Page Template |
discounts Object#
Parameter |
Type | Description |
|---|---|---|
descrip |
String | Discount Description |
discount |
Number | Discount Amount |
formatted_discount |
String | Currency-Formatted Discount Amount |
images Object#
Parameter |
Type | Description |
|---|---|---|
code |
String | Image Type Code, if assigned |
descrip |
String | Image Type Description |
sizes |
Object | Sizes will have child objects with the name width of the images. Ie. 50x50, 100x100. Original is the non-resized image |
sizes Object#
Parameter |
Type | Description |
|---|---|---|
url |
String | Full URL to Image |
width |
Number | Image Width |
height |
Number | Image |
imagetypes Object#
Parameter |
Type | Description |
|---|---|---|
descrip |
String | Image Type Description |
sizes |
Object | Sizes will have child objects with the name width of the images. Ie. 50x50, 100x100. Original is the non-resized image |
sizes Object#
Parameter |
Type | Description |
|---|---|---|
url |
String | Full URL to Image |
width |
Number | Image Width |
height |
Number | Image Height |
discounts Object#
Parameter |
Type | Description |
|---|---|---|
descrip |
String | Discount Description |
discount |
Number | Discount Amount |
formatted_discount |
String | CUrrency Formatted Discount Amount |
Example Requests#
{
"Store_Code": "{{Store_Code}}",
"Miva_Request_Timestamp": "{{$timestamp}}",
"Function": "Runtime_CategoryProductList_Load_Query",
"Session_Type": "runtime",
"Category_Code": "sale",
"Count": 0,
"Offset": 0,
"Filter": [
{
"name": "search",
"value": [
{
"field": "active",
"operator": "EQ",
"value": true
}
]
},
{
"name": "imagetypes",
"value": {
"types": ["main", "back"],
"sizes": ["original", "200x200"]
}
},
{
"name": "images",
"value": {
"sizes": ["original", "100x100", "50x50"]
}
},
{
"name": "ondemandcolumns",
"value": ["descrip", "inventory", "attributes", "sale_price", "discounts", "page", "category", "facets", "subscriptionsettings", "subscriptionterms", "CustomField_Values:*"]
}
]
}
Example Response#
{
"success": 1,
"data": {
"total_count": 1,
"start_offset": 0,
"data": [
{
"id": 1,
"code": "Shirt",
"name": "T-Shirt",
"sku": "",
"image": "",
"thumbnail": "",
"disp_order": 1,
"output_disp_order": 1,
"dt_created": {
"time_t": 1670690290,
"year": 2022,
"month": 12,
"day": 10,
"hour": 8,
"minute": 38,
"second": 10,
"timezone": -8
},
"dt_Updated": {
"time_t": 1670887991,
"year": 2022,
"month": 12,
"day": 12,
"hour": 15,
"minute": 33,
"second": 11,
"timezone": -8
},
"weight": 0.0,
"taxable": true,
"price": 25.0,
"formatted_price": "$25.00",
"retail": 25.0,
"formatted_retail": "$25.00",
"base_price": 25.0,
"formatted_base_price": "$25.00",
"quantity": 0,
"url": "https://local.coolcommerce.net:4444/mm5/merchant.mvc?Screen=PROD&Product_Code=Shirt",
"descrip": "This is the best t-shirt",
"attributes": [
{
"id": 1,
"product_id": 1,
"default_id": 0,
"disp_order": 1,
"code": "size",
"type": "select",
"attemp_id": 0,
"prompt": "Select Size",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"required": true,
"inventory": true,
"image": "",
"options": [
{
"id": 1,
"product_id": 1,
"attr_id": 1,
"disp_order": 1,
"code": "small",
"prompt": "Small",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"image": ""
},
{
"id": 2,
"product_id": 1,
"attr_id": 1,
"disp_order": 2,
"code": "medium",
"prompt": "Medium",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"image": ""
},
{
"id": 3,
"product_id": 1,
"attr_id": 1,
"disp_order": 3,
"code": "large",
"prompt": "Large",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"image": ""
}
]
},
{
"id": 2,
"product_id": 1,
"default_id": 0,
"disp_order": 2,
"code": "color",
"type": "select",
"attemp_id": 0,
"prompt": "Select Color",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"required": true,
"inventory": true,
"image": "",
"options": [
{
"id": 4,
"product_id": 1,
"attr_id": 2,
"disp_order": 4,
"code": "red",
"prompt": "Red",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"image": ""
},
{
"id": 5,
"product_id": 1,
"attr_id": 2,
"disp_order": 5,
"code": "blue",
"prompt": "Blue",
"price": 0.0,
"formatted_price": "$0.00",
"weight": 0.0,
"image": ""
}
]
}
],
"sale_price": 25.0,
"formatted_sale_price": "$25.00",
"inv_active": false,
"inv_level": "",
"inv_available": 0,
"inv_instock": 0,
"inv_short": "",
"inv_long": "",
"page": {
"id": 68,
"code": "PROD",
"title": ""
},
"category": {
"id": 9,
"code": "sale",
"name": "Sale",
"url": "https://local.coolcommerce.net:4444/mm5/merchant.mvc?Screen=CTGY&Category_Code=sale"
},
"discounts": [],
"subscriptionsettings": {
"product_id": 1,
"enabled": false,
"mandatory": false,
"can_cancel": true,
"cncl_min": 0,
"can_qty": true,
"qty_min": 0,
"can_term": true,
"term_min": 0,
"can_date": true,
"date_min": 0
},
"subscriptionterms": [],
"images": [
{
"code": "main",
"descrip": "Main",
"sizes": {
"original": {
"url": "https://local.coolcommerce.net:4444/mm5/graphics/00000001/1/shirt.jpeg",
"width": 225,
"height": 225
},
"100x100": {
"url": "https://local.coolcommerce.net:4444/mm5/graphics/00000001/1/shirt_100x100.jpeg",
"width": 100,
"height": 100
},
"50x50": {
"url": "https://local.coolcommerce.net:4444/mm5/graphics/00000001/1/shirt_50x50.jpeg",
"width": 50,
"height": 50
}
}
}
],
"imagetypes": {
"main": {
"descrip": "Main",
"sizes": {
"original": {
"url": "https://local.coolcommerce.net:4444/mm5/graphics/00000001/1/shirt.jpeg",
"width": 225,
"height": 225
},
"200x200": {
"url": "https://local.coolcommerce.net:4444/mm5/graphics/00000001/1/shirt_200x200.jpeg",
"width": 200,
"height": 200
}
}
}
},
"CustomField_Values": {
"cmp-mv-prodctgy-meta": {
"keywords": "",
"description": ""
},
"customfields": {
"Brand": "Miva, Inc"
}
}
}
],
"facets": {
"Brand": {
"type": "checkbox",
"values": [
{
"value": "Miva, Inc",
"count": 1
}
]
}
}
}
}