@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Catalog - Products
@base https://api.bigcommerce.com/stores/{store_hash}/v3
@auth ApiKey X-Auth-Token in header
@endpoints 53
@hint download_for_search
@toc catalog(53)

@endpoint GET /catalog/products
@optional {id: int, id:in: [int], channel_id:in: [int], id:not_in: [int], include: [str], include_fields: [str], exclude_fields: [str], page: int, limit: int=50, direction: str(asc/desc), sort: str(id/name/sku/price/date_modified/date_last_imported/inventory_level/is_visible/total_sold/calculated_price), categories:in: [int], id:min: int, id:max: int, id:greater: int, id:less: int, name: str, mpn: str, upc: str, price: num, weight: num, condition: str(new/used/refurbished), brand_id: int, date_modified: str(date), date_modified:max: str, date_modified:min: str, date_last_imported: str(date), date_last_imported:not: str(date), date_last_imported:max: str(date), date_last_imported:min: str(date), is_visible: bool, is_featured: int(1/0), is_free_shipping: int, inventory_level: int, inventory_level:in: [int], inventory_level:not_in: [int], inventory_level:min: int, inventory_level:max: int, inventory_level:greater: int, inventory_level:less: int, inventory_low: int, out_of_stock: int, total_sold: int, type: str(digital/physical), categories: int, keyword: str, keyword_context: str(shopper/merchant), availability: str(available/disabled/preorder), sku: str, sku:in: [str]}
@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint PUT /catalog/products
@required {Content-Type: str=application/json}
@optional {include_fields: [str]}
@returns(200) {data: [any], meta: any}
@returns(207) {data: [any], errors: map{status: int, title: str, type: str, errors: map}, meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@errors {404, 409, 413, 422}

@endpoint POST /catalog/products
@required {Content-Type: str=application/json, name: str, type: str(physical/digital), weight: num(float), price: num(float)}
@optional {include_fields: [str], sku: str, description: str, width: num(float), depth: num(float), height: num(float), cost_price: num(float), retail_price: num(float), sale_price: num(float), map_price: num, tax_class_id: num, product_tax_code: str, categories: [num], brand_id: int, brand_name: str, inventory_level: int, inventory_warning_level: int, inventory_tracking: str(none/product/variant), fixed_cost_shipping_price: num(float), is_free_shipping: bool, is_visible: bool, is_featured: bool, related_products: [int], warranty: str, bin_picking_number: str, layout_file: str, upc: str, search_keywords: str, availability_description: str, availability: str(available/disabled/preorder), gift_wrapping_options_type: str(any/none/list), gift_wrapping_options_list: [int], sort_order: int, condition: str(New/Used/Refurbished), is_condition_shown: bool, order_quantity_minimum: int, order_quantity_maximum: int, page_title: str, meta_keywords: [str], meta_description: str, view_count: int, preorder_release_date: str(date-time), preorder_message: str, is_preorder_only: bool, is_price_hidden: bool, price_hidden_label: str, custom_url: map{url: str, is_customized: bool, create_redirect: bool}, open_graph_type: str(product/album/book/drink/food/game/movie/song/tv_show), open_graph_title: str, open_graph_description: str, open_graph_use_meta_description: bool, open_graph_use_product_name: bool, open_graph_use_image: bool, gtin: str, mpn: str, date_last_imported: str, reviews_rating_sum: int, reviews_count: int, total_sold: int, custom_fields: [map{id: int, name!: str, value!: str}], bulk_pricing_rules: [any], images: [any], videos: [any], variants: [any]}
@returns(200) {data: any, meta: map}
@returns(207) {data: [any], errors: map{status: int, title: str, type: str, errors: map}, meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@errors {409, 422}

@endpoint DELETE /catalog/products
@optional {name: str, sku: str, price: num, weight: num, condition: str(new/used/refurbished), brand_id: int, date_modified: str(date), date_last_imported: str(date), is_visible: bool, is_featured: int(1/0), id:in: [int], inventory_level: int, total_sold: int, type: str(digital/physical), categories: int, keyword: str}
@returns(204)

@endpoint GET /catalog/products/{product_id}
@optional {include: [str], include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}
@required {Content-Type: str=application/json}
@optional {include: [str], include_fields: [str]}
@returns(200) {data: any, meta: map}
@returns(201)
@returns(207) {data: any, errors: map{status: int, title: str, type: str, errors: map}, meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@errors {404, 409, 422}

@endpoint DELETE /catalog/products/{product_id}
@returns(204)

@endpoint GET /catalog/products/{product_id}/images
@optional {page: int, limit: int=50, include_fields: [str], exclude_fields: [str]}
@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@returns(204)
@errors {404}

@endpoint POST /catalog/products/{product_id}/images
@returns(200) {data: any, meta: map}
@errors {400, 404, 422}

@endpoint GET /catalog/products/{product_id}/images/{image_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/images/{image_id}
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@returns(201)
@errors {400, 404, 422}

@endpoint DELETE /catalog/products/{product_id}/images/{image_id}
@returns(204)

@endpoint GET /catalog/products/{product_id}/videos
@optional {include_fields: [str], exclude_fields: [str], page: int, limit: int=50}
@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint POST /catalog/products/{product_id}/videos
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint GET /catalog/products/{product_id}/videos/{id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/videos/{id}
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint DELETE /catalog/products/{product_id}/videos/{id}
@returns(204)

@endpoint GET /catalog/products/{product_id}/complex-rules
@optional {include_fields: [str], exclude_fields: [str], page: int, limit: int=50}
@returns(200) {data: [map], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint POST /catalog/products/{product_id}/complex-rules
@required {Content-Type: str=application/json}
@optional {sort_order: int, enabled: bool, stop: bool, purchasing_disabled: bool, purchasing_disabled_message: str, purchasing_hidden: bool, image_url: str, price_adjuster: map{adjuster: str, adjuster_value: num}, weight_adjuster: map{adjuster: str, adjuster_value: num}, conditions: [any]}
@returns(200) {data: map{id: int, product_id: int?, sort_order: int, enabled: bool, stop: bool, purchasing_disabled: bool, purchasing_disabled_message: str, purchasing_hidden: bool, image_url: str, price_adjuster: map{adjuster: str?, adjuster_value: num}, weight_adjuster: map{adjuster: str?, adjuster_value: num}, conditions: [map]}, meta: map}
@errors {409, 422}

@endpoint GET /catalog/products/{product_id}/complex-rules/{complex_rule_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: map{id: int, product_id: int, sort_order: int, enabled: bool, stop: bool, purchasing_disabled: bool, purchasing_disabled_message: str, purchasing_hidden: bool, image_url: str, price_adjuster: map{adjuster: str, adjuster_value: num}, weight_adjuster: map{adjuster: str, adjuster_value: num}, conditions: [map]}, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/complex-rules/{complex_rule_id}
@required {Content-Type: str=application/json}
@optional {sort_order: int, enabled: bool, stop: bool, purchasing_disabled: bool, purchasing_disabled_message: str, purchasing_hidden: bool, image_url: str, price_adjuster: map{adjuster: str, adjuster_value: num}, weight_adjuster: map{adjuster: str, adjuster_value: num}, conditions: [map{modifier_id!: int, modifier_value_id!: int, variant_id!: int}]}
@returns(200) {data: map{id: int, product_id: int, sort_order: int, enabled: bool, stop: bool, purchasing_disabled: bool, purchasing_disabled_message: str, purchasing_hidden: bool, image_url: str, price_adjuster: map{adjuster: str, adjuster_value: num}, weight_adjuster: map{adjuster: str, adjuster_value: num}, conditions: [map]}, meta: map}
@errors {409, 422}

@endpoint DELETE /catalog/products/{product_id}/complex-rules/{complex_rule_id}
@returns(204)

@endpoint GET /catalog/products/{product_id}/custom-fields
@optional {include_fields: [str], exclude_fields: [str], page: int, limit: int=50}
@returns(200) {data: [map], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@errors {401, 403, 404, 405}

@endpoint POST /catalog/products/{product_id}/custom-fields
@required {name: str, value: str}
@returns(200) {data: map{id: int, name: str, value: str}, meta: map}
@errors {401, 403, 404, 405, 415, 422}

@endpoint GET /catalog/products/{product_id}/custom-fields/{custom_field_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: map{id: int, name: str, value: str}, meta: map}
@errors {401, 403, 404, 405}

@endpoint PUT /catalog/products/{product_id}/custom-fields/{custom_field_id}
@optional {name: str, value: str}
@returns(200) {data: map{id: int, name: str, value: str}, meta: map}
@errors {401, 403, 404, 405, 415, 422}

@endpoint DELETE /catalog/products/{product_id}/custom-fields/{custom_field_id}
@returns(204)
@errors {401, 403, 404, 405}

@endpoint POST /catalog/products/{product_id}/bulk-pricing-rules
@required {quantity_min: int, quantity_max: int, type: str(price/percent/fixed), amount: any}
@returns(200) {data: any, meta: map}

@endpoint GET /catalog/products/{product_id}/bulk-pricing-rules
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint GET /catalog/products/{product_id}/bulk-pricing-rules/{bulk_pricing_rule_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/bulk-pricing-rules/{bulk_pricing_rule_id}
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@errors {404, 409, 422}

@endpoint DELETE /catalog/products/{product_id}/bulk-pricing-rules/{bulk_pricing_rule_id}
@returns(204)
@errors {404}

@endpoint GET /catalog/products/{product_id}/metafields
@optional {page: int, limit: int=50, key: str, namespace: str, include_fields: [str], exclude_fields: [str], resource_id:in: str}
@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint POST /catalog/products/{product_id}/metafields
@required {Content-Type: str=application/json, key: str, value: str, namespace: str, permission_set: str(app_only/read/write/read_and_sf_access/write_and_sf_access)}
@optional {description: str}
@returns(200) {data: any, meta: map}
@errors {400, 409, 422}

@endpoint GET /catalog/products/{product_id}/metafields/{metafield_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/metafields/{metafield_id}
@required {Content-Type: str=application/json, key: str, value: str, namespace: str, permission_set: str(app_only/read/write/read_and_sf_access/write_and_sf_access)}
@optional {description: str}
@returns(200) {data: any, meta: map}
@errors {400, 404}

@endpoint DELETE /catalog/products/{product_id}/metafields/{metafield_id}
@returns(204)
@errors {404}

@endpoint GET /catalog/products/{product_id}/reviews
@optional {include_fields: [str], exclude_fields: [str], page: int, limit: int=50, status: int(0/1)}
@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}
@returns(204)
@errors {404}

@endpoint POST /catalog/products/{product_id}/reviews
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint GET /catalog/products/{product_id}/reviews/{review_id}
@optional {include_fields: [str], exclude_fields: [str]}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint PUT /catalog/products/{product_id}/reviews/{review_id}
@required {Content-Type: str=application/json}
@returns(200) {data: any, meta: map}
@errors {404}

@endpoint DELETE /catalog/products/{product_id}/reviews/{review_id}
@returns(204)

@endpoint GET /catalog/products/channel-assignments
@optional {page: int, limit: int=50, product_id:in: [int], channel_id:in: [int]}
@returns(200) {data: [map], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint PUT /catalog/products/channel-assignments
@required {Content-Type: str=application/json}
@returns(204)
@errors {422}

@endpoint DELETE /catalog/products/channel-assignments
@optional {product_id:in: [int], channel_id:in: [int]}
@returns(204)
@errors {422}

@endpoint GET /catalog/products/category-assignments
@optional {page: int, limit: int=50, product_id:in: [int], category_id:in: [int]}
@returns(200) {data: [map], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}}}

@endpoint PUT /catalog/products/category-assignments
@required {Content-Type: str=application/json}
@returns(204)
@errors {422}

@endpoint DELETE /catalog/products/category-assignments
@optional {product_id:in: [int], category_id:in: [int]}
@returns(204)
@errors {422}

@endpoint GET /catalog/summary
@returns(200) {data: map{inventory_count: int, inventory_value: num(double), primary_category_id: int, primary_category_name: str, variant_count: int, highest_variant_price: num(double), average_variant_price: num(double), lowest_variant_price: str, oldest_variant_date: str, newest_variant_date: str}, meta: map}

@endpoint GET /catalog/products/metafields
@optional {page: int, limit: int=50, key: str, key:in: [str], namespace: str, namespace:in: [str], direction: str(asc/desc), include_fields: [str], date_modified:min: str, date_modified:max: str, date_created:min: str, date_created:max: str, before: str, after: str}
@returns(200) {data: [map], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}, cursor_pagination: map{count: int, per_page: int, start_cursor: str, end_cursor: str, links: map{previous: str, current: str, next: str}}}}

@endpoint POST /catalog/products/metafields
@returns(200) {data: [map], errors: [any], meta: map{total: int, success: int, failed: int}}
@errors {400, 422}

@endpoint PUT /catalog/products/metafields
@returns(200) {data: [map], errors: [any], meta: map{total: int, success: int, failed: int}}
@errors {400, 422}

@endpoint DELETE /catalog/products/metafields
@returns(200) {data: [int], errors: [any], meta: map{total: int, success: int, failed: int}}
@errors {400, 422}

@end