List Products

GET

https://api.bigcommerce.com/stores/store_hash/v3/catalog/products

GET

/stores/store_hash/v3/catalog/products

1 curl -G https://api.bigcommerce.com/stores/store_hash/v3/catalog/products \
2      -H "X-Auth-Token: <apiKey>" \
3      -d date_modified=2024-07-18 \
4      -d date_last_imported=2020-07-18 \
5      -d date_last_imported:not=2020-07-18 \
6      -d date_last_imported:max=2020-07-18 \
7      -d date_last_imported:min=2020-07-18 \
8      -d is_visible=true

200Retrieved

1 {
2   "data": [
3     {
4       "availability": "available",
5       "availability_description": "string",
6       "base_variant_id": 1,
7       "bin_picking_number": "string",
8       "brand_id": 1,
9       "bulk_pricing_rules": [
10         {
11           "amount": 10,
12           "id": 1,
13           "quantity_max": 50,
14           "quantity_min": 10,
15           "type": "price"
16         }
17       ],
18       "calculated_price": 1.1,
19       "categories": [
20         1.1
21       ],
22       "channels": [
23         1
24       ],
25       "condition": "New",
26       "cost_price": 1.1,
27       "custom_fields": [
28         {
29           "name": "ISBN",
30           "value": "1234567890123",
31           "id": 6
32         }
33       ],
34       "custom_url": {
35         "url": "string",
36         "is_customized": true,
37         "create_redirect": true
38       },
39       "date_created": "2018-08-15T14:49:05+00:00",
40       "date_last_imported": "string",
41       "date_modified": "2018-08-24T14:41:00+00:00",
42       "depth": 1.1,
43       "description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
44       "fixed_cost_shipping_price": 1.1,
45       "gift_wrapping_options_list": [
46         1
47       ],
48       "gift_wrapping_options_type": "any",
49       "gtin": "string",
50       "height": 1.1,
51       "id": 1,
52       "images": [
53         {
54           "date_modified": "2024-01-15T09:30:00Z",
55           "description": "string",
56           "id": 1,
57           "image_url": "string",
58           "is_thumbnail": true,
59           "product_id": 1,
60           "sort_order": 1,
61           "url_standard": "string",
62           "url_thumbnail": "string",
63           "url_tiny": "string",
64           "url_zoom": "string"
65         }
66       ],
67       "inventory_level": 1,
68       "inventory_tracking": "none",
69       "inventory_warning_level": 1,
70       "is_condition_shown": true,
71       "is_featured": true,
72       "is_free_shipping": true,
73       "is_preorder_only": true,
74       "is_price_hidden": true,
75       "is_visible": true,
76       "layout_file": "string",
77       "map_price": 1.1,
78       "meta_description": "string",
79       "meta_keywords": [
80         "string"
81       ],
82       "modifiers": [
83         {
84           "required": true,
85           "type": "date",
86           "config": {
87             "default_value": "string",
88             "checked_by_default": true,
89             "checkbox_label": "string",
90             "date_limited": true,
91             "date_limit_mode": "range",
92             "date_earliest_value": "2023-01-15",
93             "date_latest_value": "2023-01-15",
94             "file_types_mode": "specific",
95             "file_types_supported": [
96               "images, documents, other"
97             ],
98             "file_types_other": [
99               "pdf"
100             ],
101             "file_max_size": 5,
102             "text_characters_limited": true,
103             "text_min_length": 1,
104             "text_max_length": 55,
105             "text_lines_limited": true,
106             "text_max_lines": 4,
107             "number_limited": true,
108             "number_limit_mode": "lowest",
109             "number_lowest_value": 100,
110             "number_highest_value": 1.1,
111             "number_integers_only": false,
112             "product_list_adjusts_inventory": true,
113             "product_list_adjusts_pricing": true,
114             "product_list_shipping_calc": "weight"
115           },
116           "display_name": "string",
117           "id": 12,
118           "name": "Add-a-$5-Donation1535039590-191",
119           "option_values": [
120             {
121               "label": "Green",
122               "sort_order": 0,
123               "adjusters": {
124                 "price": {
125                   "adjuster": "relative",
126                   "adjuster_value": 5
127                 },
128                 "weight": {
129                   "adjuster": "relative",
130                   "adjuster_value": 5
131                 },
132                 "image_url": "https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2",
133                 "purchasing_disabled": {
134                   "status": true,
135                   "message": "string"
136                 }
137               },
138               "id": 1,
139               "is_default": false,
140               "option_id": 1,
141               "value_data": {}
142             }
143           ],
144           "product_id": 77,
145           "sort_order": 1
146         }
147       ],
148       "mpn": "string",
149       "name": "Smith Journal 13",
150       "open_graph_description": "string",
151       "open_graph_title": "string",
152       "open_graph_type": "product",
153       "open_graph_use_image": true,
154       "open_graph_use_meta_description": true,
155       "open_graph_use_product_name": true,
156       "option_set_display": "string",
157       "option_set_id": 1,
158       "options": [
159         {
160           "id": 55,
161           "product_id": 4,
162           "display_name": "Add-a-$5-Donation1535042499-187",
163           "type": "radio_buttons",
164           "config": {
165             "default_value": "string",
166             "checked_by_default": true,
167             "checkbox_label": "string",
168             "date_limited": true,
169             "date_limit_mode": "range",
170             "date_earliest_value": "2023-01-15",
171             "date_latest_value": "2023-01-15",
172             "file_types_mode": "specific",
173             "file_types_supported": [
174               "images, documents, other"
175             ],
176             "file_types_other": [
177               "pdf"
178             ],
179             "file_max_size": 5,
180             "text_characters_limited": true,
181             "text_min_length": 1,
182             "text_max_length": 55,
183             "text_lines_limited": true,
184             "text_max_lines": 4,
185             "number_limited": true,
186             "number_limit_mode": "lowest",
187             "number_lowest_value": 100,
188             "number_highest_value": 1.1,
189             "number_integers_only": false,
190             "product_list_adjusts_inventory": true,
191             "product_list_adjusts_pricing": true,
192             "product_list_shipping_calc": "weight"
193           },
194           "sort_order": 1,
195           "option_values": [
196             {
197               "label": "Green",
198               "sort_order": 0,
199               "id": 1,
200               "is_default": false,
201               "value_data": {}
202             }
203           ]
204         }
205       ],
206       "order_quantity_maximum": 1,
207       "order_quantity_minimum": 1,
208       "page_title": "string",
209       "preorder_message": "string",
210       "preorder_release_date": "2024-01-15T09:30:00Z",
211       "price": 1.1,
212       "price_hidden_label": "string",
213       "primary_image": {
214         "id": 1,
215         "product_id": 1,
216         "is_thumbnail": true,
217         "sort_order": 1,
218         "description": "string",
219         "image_file": "string",
220         "url_zoom": "string",
221         "url_standard": "string",
222         "url_thumbnail": "string",
223         "url_tiny": "string",
224         "date_modified": "2024-01-15T09:30:00Z"
225       },
226       "product_tax_code": "string",
227       "related_products": [
228         1
229       ],
230       "retail_price": 1.1,
231       "reviews_count": 4,
232       "reviews_rating_sum": 3,
233       "sale_price": 1.1,
234       "search_keywords": "string",
235       "sku": "SM-13",
236       "sort_order": 1,
237       "tax_class_id": 1.1,
238       "total_sold": 80,
239       "type": "physical",
240       "upc": "string",
241       "videos": [
242         {
243           "description": "A video about documenation",
244           "id": 1,
245           "length": "string",
246           "product_id": 1,
247           "sort_order": 1,
248           "title": "Writing Great Documentation",
249           "type": "youtube",
250           "video_id": "z3fRu9pkuXE"
251         }
252       ],
253       "warranty": "string",
254       "weight": 1.1,
255       "width": 1.1,
256       "view_count": 1
257     }
258   ],
259   "meta": {
260     "pagination": {
261       "total": 36,
262       "count": 36,
263       "per_page": 50,
264       "current_page": 1,
265       "total_pages": 1,
266       "links": {
267         "previous": "string",
268         "current": "?page=1&limit=50",
269         "next": "string"
270       }
271     }
272   }
273 }

Returns a list of Products. Optional filter parameters can be passed in.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Products	modify	`store_v2_products`
Products	read-only	`store_v2_products_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Query parameters

idintegerOptional

Filter items by product ID.

id:inlist of integersOptional

Pass a comma-separated list to filter by one or more product IDs.

channel_id:inlist of integersOptional

Pass a comma-separated list to filter by one or more channel IDs.

id:not_inlist of integersOptional

Pass a comma-separated list to exclude one or more product IDs.

includelist of enumsOptional

A comma-separated list of sub-resources to return with a product object. When you specify options or modifiers, results are limited to 10 per page.

include_fieldslist of enumsOptional

Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

exclude_fieldslist of stringsOptional

Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

pageintegerOptional

Specifies the page number in a limited (paginated) list of products.

limitintegerOptional<=250Defaults to 50

Controls the number of items per page in a limited (paginated) list of products.

directionenumOptional

Sort direction. Acceptable values are: asc, desc.

Allowed values:

sortenumOptional

Field name to sort by. Note: Since ID increments when new products are added, you can use the ID value to sort by product create date.

categories:inlist of integersOptional

A comma-separated list of category IDs. Returns a list of products that are in all the categories specified.

id:minintegerOptional

id:maxintegerOptional

id:greaterintegerOptional

id:lessintegerOptional

namestringOptional

Filter items by name.

mpnstringOptional

Filter items by Manufacturer Part Number (MPN).

upcstringOptional

Filter items by UPC.

pricedoubleOptional

Filter items by price.

weightdoubleOptional

Filter items by weight.

conditionenumOptional

Filter items by condition.

Allowed values:

brand_idintegerOptional

Filter items by brand ID.

date_modifieddateOptional

Filter items by date_modified.

date_modified:maxstringOptional

Filter items by date_modified. If the date modified:max does not include hours, minutes and seconds, the API automatically adds the current time of the request to the date. For example, date_modified:max=2025-01-15 or date_modified:max=2025-01-15T00:03:17Z.

date_modified:minstringOptional

Filter items by date_modified. If the date modified:min does not include hours, minutes and seconds, the API automatically adds the current time of the request to the date. For example, date_modified:min=2025-01-15 or date_modified:min=2025-01-15T00:03:17Z.

date_last_importeddateOptional

Filter items by date_last_imported.

date_last_imported:notdateOptional

Filter products by specifying a date they were NOT last imported. For example, date_last_imported:not=2015-08-21T22%3A53%3A23%2B00%3A00.

date_last_imported:maxdateOptional

Filter items by date_last_imported. For example, date_last_imported:max=2015-08-21T22%3A53%3A23%2B00%3A00.

date_last_imported:mindateOptional

Filter items by date_last_imported. For example, date_last_imported:min=2015-08-21T22%3A53%3A23%2B00%3A00.

is_visiblebooleanOptional

Filter items based on whether the product is currently visible on the storefront.

is_featuredenumOptional

Filter items by is_featured. 1 for true, 0 for false.

Allowed values:

is_free_shippingintegerOptional

Filter items by is_free_shipping. 1 for true, 0 for false.

inventory_levelintegerOptional

Filter items by inventory_level.

inventory_level:inlist of integersOptional

A comma-separated list of inventory levels. Returns a list of all products that have any of the listed inventory amounts.

inventory_level:not_inlist of integersOptional

A comma-separated list of inventory levels. Returns a list of all products that have inventory amounts other than those specified.

inventory_level:minintegerOptional

inventory_level:maxintegerOptional

inventory_level:greaterintegerOptional

inventory_level:lessintegerOptional

inventory_lowintegerOptional

Filter items by inventory_low. Values: 1, 0.

out_of_stockintegerOptional

Filter items by out_of_stock. To enable the filter, pass out_of_stock=1.

total_soldintegerOptional

Filter items by total_sold.

typeenumOptional

Filter items by type.

Allowed values:

categoriesintegerOptional

Filter items by categories. If a product is in more than one category, using this query will not return the product. Instead use categories:in=12.

keywordstringOptional

Filter items by keywords found in the name, description, or sku fields, or in the brand name.

keyword_contextenumOptional

Set context used by the search algorithm to return results targeted towards the specified group. Use merchant to help merchants search their own catalog. Use shopper to return shopper-facing search results.

Allowed values:

availabilityenumOptional

Filter items by availability. Values are: available, disabled, preorder.

Allowed values:

skustringOptional

Filter items by main SKU. To filter by variant SKU, see Get all variants.

sku:inlist of stringsOptional

A comma-separated list of SKUs. Returns a list of products with those SKUs.

Response

datalist of objects

metaobject

Data about the response, including pagination and collection totals.

List Products

Authentication

OAuth scopes

Authentication header

Further reading

Query parameters

Response

OAuth scopes

Authentication header

Further reading