Runtime_ProductList_Load_Query#
Description#
This is a runtime function intended to be called client side to query product data. 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 |
|---|---|---|
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. |
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 |
On Demand Columns#
Column |
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#
Column |
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. |
fragments |
This filter will return the output of a comma separated fragment code list. (Introduced in Version 10.10.00) |
variant_id |
This filter will return the attribute option value of the value passed. (Introduced in Version 10.12.00) |
When variant_id is present
- All price, weight output (including formatted variations) will reflect the variant if present and valid. This includes variants that use “master” pricing; in this case the price of the variant-applied attributes will automatically be added to the master product price. Sorting by price will not reflect the variant.
- Inventory values shall reflect the variant, if it is present and valid. Products that are out of stock at the variant level will not be hidden. Products that are out of stock at the master product level, but in stock at the variant level, will be hidden. This is consistent with other locations in the software.
sale_pricewill reflect the variant, if it is present and valid. Sorting by price will not reflect the variant.- Calculated discounts shall reflect the variant, if it is present and valid.
- Output images shall reflect the variant, if it is present and valid.
Supported Sort Columns#
One of these values would be passed in the sort request parameter to have the results sorted by that column.
Column Name |
Description |
|---|---|
relevance |
Specifies relevance sorting. |
customfield/customfield_desc |
Sorting based on custom field in ascending or descending order. |
disp_order/disp_order_desc |
Sorting based on display order in ascending or descending order. |
newest |
Sorts items by newest first. |
oldest |
Sorts items by oldest first. |
updated |
Sorts items by last updated. |
code_asc |
Sorts items alphabetically by code in ascending order. |
code_desc |
Sorts items alphabetically by code in descending order. |
name_asc |
Sorts items alphabetically by name in ascending order. |
name_desc |
Sorts items alphabetically by name in descending order. |
price_asc |
Sorts items by price in ascending order. |
price_desc |
Sorts items by price in descending order. |
bestsellers |
Sorts items 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 | [Depreciated] This field is depreciated and is supported for legacy purposes. Relative Path to the product fullsize image. |
thumbnail |
String | [Depreciated] 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 |
Sting | Canonical Category Code 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. |
CustomField_Values:* |
Object | See custom field usage here: List Load Query Overview |
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 |
value |
String | When a variant_id for the output product is present the option value will output.text and memo attributes will never have a value present.checkbox attributes will have a value that is JSON true/false.Other types will contain the code of the selected option. |
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_ProductList_Load_Query",
"Session_Type": "runtime",
"Count": 0,
"Offset": 0,
"Filter": [
{
"name": "search",
"value": [
{
"field": "active",
"operator": "EQ",
"value": true
}
]
},
{
"name": "variant_id",
"value": {
"shirt": 10
}
},
{
"name": "runtime_search",
"value": "shirt"
},
{
"name": "facets",
"value": {
"Brand": "My Custom Brand"
}
},
{
"name": "imagetypes",
"value": {
"types": ["main", "back"],
"sizes": ["original", "200x200"]
}
},
{
"name": "images",
"value": {
"sizes": ["original", "100x100", "50x50"]
}
},
{
"name": "fragments",
"value": ["fragment_1", "fragment_2", "fragment_3"]
},
{
"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": "Shirt",
"sku": "",
"image": "",
"thumbnail": "",
"disp_order": 1,
"output_disp_order": 0,
"dt_created": {
"time_t": 1669936337,
"year": 2022,
"month": 12,
"day": 1,
"hour": 15,
"minute": 12,
"second": 17,
"timezone": -8
},
"dt_Updated": {
"time_t": 1670625382,
"year": 2022,
"month": 12,
"day": 9,
"hour": 14,
"minute": 36,
"second": 22,
"timezone": -8
},
"weight": 0.0,
"taxable": true,
"price": 20.0,
"formatted_price": "$20.00",
"retail": 25.0,
"formatted_retail": "$25.00",
"base_price": 25.0,
"formatted_base_price": "$25.00",
"quantity": 0,
"url": "https://local.coolcommerce.net/mm5/merchant.mvc?Screen=PROD&Product_Code=shirt",
"descrip": "This <span style=\"background-color: rgb(199, 0, 0);\">is the</span> product<span style=\"text-decoration-line: line-through;\"> Description</span>",
"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": 5.0,
"formatted_price": "$5.00",
"weight": 0.0,
"image": ""
}
],
"value": "large"
}
],
"sale_price": 20.0,
"formatted_sale_price": "$20.00",
"inv_active": false,
"inv_level": "",
"inv_available": 0,
"inv_instock": 0,
"inv_short": "",
"inv_long": "",
"page": {
"id": 68,
"code": "PROD",
"title": ""
},
"discounts": [
{
"descrip": "20OFF",
"discount": 5.0,
"formatted_discount": "$5.00"
}
],
"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/mm5/graphics/00000002/1/shirt.jpeg",
"width": 225,
"height": 225
},
"100x100": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt_100x100.jpeg",
"width": 100,
"height": 100
},
"50x50": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt_50x50.jpeg",
"width": 50,
"height": 50
}
}
},
{
"code": "",
"descrip": "",
"sizes": {
"original": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/image2.jpeg",
"width": 440,
"height": 440
},
"100x100": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/image2_100x100.jpeg",
"width": 100,
"height": 100
},
"50x50": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/image2_50x50.jpeg",
"width": 50,
"height": 50
}
}
},
{
"code": "",
"descrip": "",
"sizes": {
"original": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt.jpg",
"width": 500,
"height": 625
},
"100x100": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt_80x100.jpg",
"width": 80,
"height": 100
},
"50x50": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt_40x50.jpg",
"width": 40,
"height": 50
}
}
}
],
"imagetypes": {
"main": {
"descrip": "Main",
"sizes": {
"original": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt.jpeg",
"width": 225,
"height": 225
},
"200x200": {
"url": "https://local.coolcommerce.net/mm5/graphics/00000002/1/shirt_200x200.jpeg",
"width": 200,
"height": 200
}
}
}
},
"fragments":{
"fragment_1": "Fragment 1 that references the shirt product",
"fragment_2": "Fragment 2 that references the shirt product",
"fragment_3": "Fragment 3 that references the shirt product"
},
"CustomField_Values": {
"cmp-mv-prodctgy-meta": {
"keywords": "",
"description": ""
},
"customfields": {
"Brand": "My Custom Brand"
}
}
}
],
"facets": {
"Brand": {
"type": "checkbox",
"values": [
{
"value": "My Custom Brand",
"count": 1
}
]
}
}
}
}