API2Cart API v.1.1: Guideline on How to Work with Product Endpoints


First, we recommend you to explore the Product Methods documentation. Most methods support filters like modified_from, modified_to.


When working with shopping platforms that support multilanguage or/and multistore, you need to pass store_id and/or lang_id parameters. In case the parameter is not passed, we automatically set the default value of store_id and lang_id. 


API2Cart returns response only for one language and one store in one request. To get the data for other stores or in other languages, send a request specifying other store_id and lang_id. Use cart.info method to retrieve the list of stores and languages if they are multiple. 


Use product.count method to get the amount of products.


Use product.list or product.info to get information on products. The response structure can be found in the end of description of each method. 


There can be the following types of products in product.list or product.info response: simple, virtual, configurable, bundle, grouped, downloadable, gift_card. For WooCommerce there are also supported simple-subscription і configurable-subscription product types.


Simple - a simple product that can be a standalone product or as a part of configurable, bundle or grouped product.


Virtual - a non-physical product like service, warranty, subscription. It can be a standalone product or a part of configurable or grouped types.


Configurable - a product that contains variants based on option combinations.


Bundle - a product that consists of separate products both physical and virtual. The customer can select which products and how many of them will form the final bundle product. This product type is often used in in electronics, e.g. cameras or computers.


Grouped - several separate products gathered into a group. You can find the ids of products included in a group in the grouped_products_ids massive in response of product.list or product.info. To get the info about these products, use product.list method specifying products_ids parameter. The parameter value must be unique ids that are in grouped_products_ids.


Downloadable - an electronic product that can be downloaded: multimedia or software.


Gift_card - a gift certificate of a certain value.


Simple-subscription and configurable-subscription are similar to virtual products. These types are used only in WooCommerce stores when WooCommerce Subscriptions module is active. Configurable-subscription type has variants.


To get variants or bundle items use product.child_item.list, specifying product_id or product_ids parameter to get list of child items of a certain product or few. If you specify “product_id=1”, the method will return child items for product with id=1, using product_ids parameter you can get list of child items for multiple products (max 100).


Product.child_item.list does not have a separate method for getting total number of child items. However, there is a total_count field in response that returns the total number of child items for a specific request with the specified parameters. For example, if you make two requests for the same product_ids, but in one request you specify avail_sale parameter, their total_count values can be different. There can be requests with zero count, in that case you can find out only the number of variants, for example “product.child_item.list.json?product_ids=a,b,c&count=0”.


Product.child_item.list method has a combination field in response, which contains option ids and their values that form a particular variant or bundle item. But not always all the options contained in the product form a combination of variants. Some platforms (like Magento or WooCommerce) allow custom options, that don’t form combination but allow to additionally customize the product, even if it has variants.


Use “params=force_all” parameter only when you really need all the available information. Otherwise, it is better to specify the needed fields, for example  “params=id, name, price, advanced_price, quantity”.


Data retrieval order:


  1. Retrieve the needed products using product.list or product.info methods

  2. Get product ids if the type of product is configurable, bundle or  configurable-subscription

  3. Get all ids from grouped_products_ids if the product type is grouped

  4. Retrieve variants and bundle components using product.child_item.list method specifying product_ids parameter. (See how to get product ids in step 3)

  5. Retrieve all products contained in groups using product.list method specifying product_ids parameter. (See how to get product ids in step 3)


An example of data retrieval for products and their child items (variant, bundle items).


  1. Call product.list or product.info method and collect received ids for products of configurable or bundle types.


Request example:

product.list.json?api_key=xxxxx&store_key=xxxxx&start=0&count=5&params=id,name,price,type,product_options


Response example:



{

  "return_code": 0,

  "return_message": "",

  "result": {

    "product": [

      {

        "id": "93",

        "type": "configurable",

        "name": "[Sample] 1 L Le Parfait Jar",

        "price": 9.95,

        "product_options": [

          {

            "id": "32",

            "product_option_id": 112,

            "name": "Size",

            "description": "Size",

            "sort_order": 1,

            "type": "radio",

            "required": true,

            "option_items": [

              {

                "id": "95",

                "product_option_item_id": null,

                "name": "Small",

                "sort_order": 0,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "Small"

                }

              },

              {

                "id": "96",

                "product_option_item_id": null,

                "name": "Medium",

                "sort_order": 1,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "Medium"

                }

              },

              {

                "id": "97",

                "product_option_item_id": null,

                "name": "Large",

                "sort_order": 2,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "Large"

                }

              }

            ],

            "additional_fields": {

              "default_option_id": null

            }

          },

          {

            "id": "3",

            "product_option_id": 111,

            "name": "Color",

            "description": "Color",

            "sort_order": 0,

            "type": "radio",

            "required": true,

            "option_items": [

              {

                "id": "7",

                "product_option_item_id": null,

                "name": "Silver",

                "sort_order": 1,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#cccccc"

                }

              },

              {

                "id": "8",

                "product_option_item_id": null,

                "name": "Black",

                "sort_order": 2,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#000000"

                }

              },

              {

                "id": "10",

                "product_option_item_id": null,

                "name": "Blue",

                "sort_order": 4,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#123c91"

                }

              },

              {

                "id": "13",

                "product_option_item_id": null,

                "name": "Orange",

                "sort_order": 7,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#e35e20"

                }

              }

            ],

            "additional_fields": {

              "default_option_id": null

            }

          }

        ]

      },

      {

        "id": "107",

        "type": "configurable",

        "name": "[Sample] Dustpan & Brush",

        "price": 34.95,

        "product_options": [

          {

            "id": "3",

            "product_option_id": 114,

            "name": "Color",

            "description": "Color",

            "sort_order": 0,

            "type": "radio",

            "required": true,

            "option_items": [

              {

                "id": "7",

                "product_option_item_id": null,

                "name": "Silver",

                "sort_order": 1,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#cccccc"

                }

              },

              {

                "id": "8",

                "product_option_item_id": null,

                "name": "Black",

                "sort_order": 2,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#000000"

                }

              },

              {

                "id": "10",

                "product_option_item_id": null,

                "name": "Blue",

                "sort_order": 4,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#123c91"

                }

              },

              {

                "id": "13",

                "product_option_item_id": null,

                "name": "Orange",

                "sort_order": 7,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "#e35e20"

                }

              }

            ],

            "additional_fields": {

              "default_option_id": null

            }

          }

        ]

      },

      {

        "id": "111",

        "type": "simple",

        "name": "[Sample] Smith Journal 13",

        "price": 25,

        "product_options": [

          {

            "id": "31",

            "product_option_id": 113,

            "name": "EULA",

            "description": "EULA",

            "sort_order": 0,

            "type": "checkbox",

            "required": true,

            "option_items": [

              {

                "id": "93",

                "product_option_item_id": null,

                "name": "Yes",

                "sort_order": 0,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "Yes"

                }

              },

              {

                "id": "94",

                "product_option_item_id": null,

                "name": "No",

                "sort_order": 1,

                "price": 0,

                "weight": 0,

                "quantity": null,

                "type_price": "percent",

                "sku": null,

                "additional_fields": {

                  "full_description": "No"

                }

              }

            ],

            "additional_fields": {

              "default_option_id": "94"

            }

          }

        ]

      }

    ]

  }

}



2) Call product.child_item.list specifying “product_ids” parameter


Request example: 

product.child_item.list.json?api_key=xxxxx&store_key=xxxxxx&start=5&count=10&params=id,default_price,advanced_price,combination,sku,parent_id&product_ids=93,107


Response example:



{

  "return_code": 0,

  "return_message": "",

  "result": {

    "total_count": 16,

    "children": [

      {

        "id": "56",

        "parent_id": "93",

        "sku": "SLLPJ-973630F5",

        "combination": [

          {

            "option_id": "111",

            "option_value_id": "10"

          },

          {

            "option_id": "112",

            "option_value_id": "97"

          }

        ],

        "default_price": 7,

        "advanced_price": [

          {

            "id": "sp",

            "value": 7,

            "avail": true,

            "group_id": null,

            "quantity_from": null,

            "start_time": null,

            "expire_time": null

          }

        ]

      },

      {

        "id": "57",

        "parent_id": "93",

        "sku": "SLLPJ-889E9C0A",

        "combination": [

          {

            "option_id": "111",

            "option_value_id": "13"

          },

          {

            "option_id": "112",

            "option_value_id": "97"

          }

        ],

        "default_price": 7,

        "advanced_price": [

          {

            "id": "sp",

            "value": 7,

            "avail": true,

            "group_id": null,

            "quantity_from": null,

            "start_time": null,

            "expire_time": null

          }

        ]

      },

      {

        "id": "77",

        "parent_id": "107",

        "sku": "SIL-EDF0AC9C",

        "combination": [

          {

            "option_id": "114",

            "option_value_id": "7"

          }

        ],

        "default_price": 34.95,

        "advanced_price": [

          

        ]

      },

      {

        "id": "78",

        "parent_id": "107",

        "sku": "BLA-6D013D80",

        "combination": [

          {

            "option_id": "114",

            "option_value_id": "8"

          }

        ],

        "default_price": 34.95,

        "advanced_price": [

          

        ]

      },

      {

        "id": "79",

        "parent_id": "107",

        "sku": "BLU-2D71C660",

        "combination": [

          {

            "option_id": "114",

            "option_value_id": "10"

          }

        ],

        "default_price": 34.95,

        "advanced_price": [

          

        ]

      },

      {

        "id": "80",

        "parent_id": "107",

        "sku": "ORA-446C93BB",

        "combination": [

          {

            "option_id": "114",

            "option_value_id": "13"

          }

        ],

        "default_price": 34.95,

        "advanced_price": [

          

        ]

      }

    ]

  }

}