ItemList Resource
Use the ItemList resource to fetch multiple items.
See Item Resource for information about related resources.
Schema type
Use item-list to reference this resource in the template schema.
Querying
Filters nullable
-
ids string[]
Array of Square
Itemids of items to retrieve. Having this filter negates anysortfilter defined on the sameitem-listresource. Maximum of 50.{ "filters": { "ids": ["WUH4RMB3WUDBQJQAOMYN56WD", "AUH4RMB3WUDBOLPDOMYN56WD"] } } -
square_online_id boolean
Flag to identify the resource to be fetched using legacy
square_online_ids{ "filters": { "ids": ["3", "4", "2"], "square_online_id": true } } - location_id string
- Default: Catalog Shipping Location ID
ID of location to scope an item to. The item data received will be based off of the item’s configuration at the given location. Must be used in conjunction with
filters.idorfilters.ids{ "filters": { "ids": ["2"], "location_id": "location_id" } } -
category_id string
Filter your items by a given
idof aCategory. Only applies whenfilters.idsis not set.{ "filters": { "category_id": "II4VPMMREFDLJ27TKULXOVMS" } } -
category_ids string[]
Filter your items by an array of
ids of aCategory. Takes precedence overfilters.id.{ "filters": { "category_ids": ["II4VPMMREFDLJ27TKULXOVMS", "NIJIIMAJJX4LZ4KF2MKHTGNY"] } } -
price_min numeric
Return items that are above a given
price_min. Only applies whenfilters.idsis not set.{ "filters": { "price_min": 10 } } -
price_max numeric
Return items that are above a given
price_max. Only applies whenfilters.idsis not set.{ "filters": { "price_max": 88.50 } } -
search string
Returns items that match the search term. Only applies when
filters.idsis not set.{ "filters": { "search": "t-shirts" } } -
similar_item_ids string[]
Returns items that are similar to the given list of IDs. Only applies when
filters.idsis not set.{ "filters": { "square_online_id": true "similar_item_ids": [ "10" ] } } -
status string[]
-
status.in_stock string
Filters list of items depending on inventory stock status. Items denoted as sold out will be removed from the list
{ "filters": { "status": [ "in_stock" ] } } -
status.on_sale string
Filters list of items that are on sale. Only items that have a sale price will be returned in the items list.
{ "filters": { "status": [ "on_sale" ] } }
-
-
fulfillments string[]
Returns items that are available under the chosen fulfillment methods
{ "filters": { "fulfillments": [ "PICKUP", "SHIPMENT", "MANUAL" ] } } -
has_discounts boolean
Flag to only return items that have discounts.
{ "filters": { "has_discounts": true } } -
option_choices string[]
Allows the filtering of items based on specific option choices. The IDs to use can be found on the Category Options Resource on the
idproperty on one of the objects in thechoicesarray.{ "filters": { "option_choices": [ "7YKSUS556XMD22P5HYIVB3P7" ] } }
List Rendering
When filters.ids is not defined, the first page (length: 100) of items will return as a result.
{ // Fetches first page of items and filters out each out of stock item
"filters": {
"status": [
"in_stock"
]
}
}
Pagination
- pagination.page_size number
- Default: 100
Control the page size of the item list request. Does not apply to
filters.idsrequests.{ "filters": { "status": [ "in_stock" ] }, "pagination": { "page_size": 50 } } - pagination.page number
- Default: 1
Control the page number of the item list request. Does not apply to
filters.idsrequests.{ "pagination": { "page_size": 50, "page": 2 } } -
pagination.meta_name string nullable
Used to set the name for this resource when loaded via a resource function for use with the
paginate_metafunction. Note that this field is ignored for resources loaded via a template’s schema, as the resource name itself is used for thepaginate_metafunction. - pagination.page_query_param string
- Default:
{property_name}_page
Control the query param that loads the page number of the item list. By default, the query param used is the name of the property with
_pageattached as a suffix. Does not apply tofilters.idsrequests.{ "sale_items": { "pagination": { "page_size": 50, "page_query_param": "page" } } }Results in
mysite.com/shop?page=4to load the fourth page of the correlating item list. By default, the pagination query parameter would besale_items_pageif no query parameter override was provided - Default:
Sorting
-
sort.by string Sort items in response by a given term. Does not apply to
filters.idsrequests.{ "filters": { "status": ["in_stock"] }, "sort": { "by": "name" } }Valid terms:
- name - price - category_order - created_date - inventory - custom_order - popularity_score -
sort.order string
- Default: “asc”
Sort order of items in response.
{ "sort": { "order": "desc" } }Valid terms:
- asc - desc
Output
[{
"__SO_RESOURCE_TYPE__": "item", // internally used resource property. do not modify.
"id": "WUH4RMB3WUDBQJQAOMYN56WD",
"square_online_id": "12",
"resource_type": "ITEM",
"name": "Turtle T-shirt",
"description": "The best t-shirt.",
"description_html": "<p>The best t-shirt.</p>",
"visibility": "VISIBLE",
"item_type": "REGULAR",
"available": true,
"is_alcoholic": false,
"price": {
"high": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"high_with_modifiers": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"high_with_subscriptions": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"low": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"low_with_modifiers": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"low_with_subscriptions": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_high": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_high_with_modifiers": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_high_with_subscriptions": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_low": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_low_with_modifiers": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_low_with_subscriptions": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
},
"images": [
{
"absolute_url": "https://769244280274161852.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p12_i1_w679.jpeg",
"width": 679,
"height": 690,
"format": "jpeg",
"absolute_urls": {
"80": "https://769244280274161852.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p12_i1_w679.jpeg?width=80",
"160": "https://769244280274161852.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p12_i1_w679.jpeg?width=160",
"320": "https://769244280274161852.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p12_i1_w679.jpeg?width=320",
"640": "https://769244280274161852.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p12_i1_w679.jpeg?width=640"
}
}
],
"item_options": [
{
"choices": [
"Black",
"Blue",
"Green",
"Yellow",
"Pink",
"White"
],
"colors": [
"#000000",
"#5174D1",
"#036E30",
"#F7C03E",
"#EF476F",
"#FFFFFF"
],
"id": "U5R73HPO2AFZMKNCD6UARS5W",
"name": "Colors FROM SQ",
"ordinal": 0,
"renderer": "color"
},
{
"choices": [
"Small",
"Medium",
"Large"
],
"id": "546RS5FESPR54V37TZMEMLSN",
"name": "Size",
"ordinal": 1,
"renderer": "radio"
}
],
"modifier_lists": [
{
"id": "U5R73HPO2AFZMKNCD6UAR7W",
"name": "T-shirt Text",
"square_online_item_id": "12",
"type": "text",
"min_selected_modifiers": 0,
"max_selected_modifiers": 150
}
],
"variations": [
{
"id": "U5R73HPO2AFZMKNCD6UARS5W",
"square_online_item_id": "12",
"square_online_id": "18",
"name": null,
"item_option_values": [
{
"id": "11ede91039dfd0649aeea665c5e5c441",
"name": "Colors",
"choice": "White",
"color": "#FFFFFF"
},
{
"id": "11ede911e2d49df281faa665c5e5c441",
"name": "Size",
"choice": "Large"
}
],
"ordinal": 18,
"price": {
"current": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"sale": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"high": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
},
"pricing_type": "FIXED_PRICING",
"sold_out": false,
"inventory": 0
}
],
"badges": {
"low_stock": false,
"out_of_stock": false,
"on_sale": false
},
"seo": {
"page_description": null,
"page_title": null
},
"open_graph": {
"title": null,
"description": null
},
"avg_rating": null,
"avg_rating_all": null,
"inventory": {
"total": 0,
"lowest": null,
"enabled": false,
"all_variations_sold_out": false,
"some_variations_sold_out": false
},
"measurement_units": {
"multiple_units": false,
"abbreviation": null,
"precision": null
},
"fulfillment": {
"methods": {
"SHIPMENT": true,
"PICKUP": true,
"DELIVERY": false,
"DINE_IN": false,
"MANUAL": false,
"DIGITAL": false
},
"methods_at_any_location": {
"SHIPMENT": true,
"PICKUP": false,
"DELIVERY": false,
"DINE_IN": false,
"MANUAL": false,
"DIGITAL": false
}
},
"fulfillment_availability": {
"PICKUP": [],
"SHIPMENT": []
},
"categories": [],
"discounts": [
{
"id": "X6P5OQ3GBC6CNHTLQIN7QP3C",
"name": "schedulealways",
"discount_type": "FIXED_PERCENTAGE",
"percentage": 1.0,
"display_strings": {
"discount_formatted": "1%",
"summary_text": "Buy 2, get 1% off each",
"badge_text": "Buy 2, get 1% off each",
"excluded_summary_text": "",
"excluded_badge_text": "",
"details": [
"Buy 2, get 1% off each",
"Automatically applied in cart to qualifying orders. If multiple discounts are available on an item, the highest-value discount is applied."
],
"recurring_details": [
"Monday from 12:00 AM - 11:59 PM",
"Tuesday from 12:00 AM - 11:59 PM",
"Thursday from 12:00 AM - 11:59 PM",
"Friday from 12:00 AM - 11:59 PM",
"Saturday from 12:00 AM - 11:59 PM"
]
},
"match_item_ids": [],
"exclude_item_ids": [],
"all_items": true,
"present_at_all_locations": true,
"absent_at_location_ids": [],
"present_at_location_ids": [],
"valid_from_date": null,
"valid_until_date": null,
"time_periods": [
"BEGIN:VEVENT\nDURATION:PT23H59M\nRRULE:FREQ=WEEKLY;BYDAY=MO\nDTSTART:20170102T000000\nEND:VEVENT\n",
"BEGIN:VEVENT\nDURATION:PT23H59M\nRRULE:FREQ=WEEKLY;BYDAY=TU\nDTSTART:20170103T000000\nEND:VEVENT\n",
"BEGIN:VEVENT\nDURATION:PT23H59M\nRRULE:FREQ=WEEKLY;BYDAY=TH\nDTSTART:20170105T000000\nEND:VEVENT\n",
"BEGIN:VEVENT\nDURATION:PT23H59M\nRRULE:FREQ=WEEKLY;BYDAY=FR\nDTSTART:20170106T000000\nEND:VEVENT\n",
"BEGIN:VEVENT\nDURATION:PT23H59M\nRRULE:FREQ=WEEKLY;BYDAY=SA\nDTSTART:20170107T000000\nEND:VEVENT\n"
],
"discount_tags": [
"quantity_exact",
"time_period"
],
"excluded_quantity": null,
"included_quantity": null,
"exact_quantity": 2,
"min_quantity": null,
"min_value": "$0",
"max_value": "$0"
}
],
"preordering": {
"PICKUP": false,
"DELIVERY": false,
"SHIPMENT": false,
"DINE_IN": false,
"MANUAL": false,
"DIGITAL": false
},
"prep_time_duration": {
"in_minutes": 30,
"rfc3339_interval": "PT30M"
},
"reviews": [
{
"reviewer_name": "Andrew Y.",
"rating": 5,
"content": "Good product",
"status": "approved",
"verified_purchase": true,
"published_replies": [],
"images": [
{
"absolute_url": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg",
"width": null,
"height": null,
"format": "jpeg",
"absolute_urls": {
"80": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg?width=80",
"160": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg?width=160",
"320": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg?width=320",
"640": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg?width=640",
"1280": "https://769244280274161852.staging.weebly.net/uploads/b/cdfd8173bb4497a4cc9a37c03725153f621a2165e584ab66a4bfe314351724d0/5d13d6a0-a665-4a31-a2a2-ee24693c5b04.jpeg?width=1280"
}
}
],
"updated_at": "2023-05-17T22:27:49+00:00"
}
],
"review_meta": {
"avg_rating": 5,
"rating_breakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 1,
"total": 1
}
},
"subscriptions": [
{
"id": "M35RH6VYGATAHIP5FKO6JVBM",
"type": "SUBSCRIPTION_PLAN",
"version": 1690496928533,
"present_at_all_locations": true,
"subscription_plan_data": {
"name": "monthly",
"subscription_plan_variations": [
{
"type": "SUBSCRIPTION_PLAN_VARIATION",
"id": "SV4O2HJUHLZS3LCDNAYNN6UP",
"present_at_all_locations": true,
"subscription_plan_variation_data": {
"name": "monthly",
"subscription_plan_id": "M35RH6VYGATAHIP5FKO6JVBM",
"monthly_billing_anchor_date": 17,
"configuration": {
"buyer_allow_indefinite_pausing": true,
"buyer_max_cycles_to_skip": 0
},
"phases": [
{
"id": "VHFPVNBPIH3H464VBTUQPZ53",
"cadence": "MONTHLY",
"ordinal": 0,
"pricing": {
"type": "RELATIVE",
"discount_ids": [
"VG5I5BC4PJJQZTDHI2JUZ7PB"
],
"regular_high": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_high_subscription": {
"amount": 1710,
"currency": "USD",
"formatted": "$17.10"
},
"regular_low": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"regular_low_subscription": {
"amount": 1710,
"currency": "USD",
"formatted": "$17.10"
},
"high": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"high_subscription": {
"amount": 1710,
"currency": "USD",
"formatted": "$17.10"
},
"low": {
"amount": 1800,
"currency": "USD",
"formatted": "$18.00"
},
"low_subscription": {
"amount": 1710,
"currency": "USD",
"formatted": "$17.10"
}
}
}
]
}
}
],
"eligible_item_ids": [
"A56GLJN57UQWINMKYA6SXNHJ",
"34ZTBGU2KOTMFXIF5EEJRAZX"
]
}
}
]
}]