Product API reference

Learn how to make Product API requests to retrieve product data for a site.

Requests

URL

The URL for Product API requests is https://<platform_instance>/productApi, where <platform_instance> is the domain name of your Frosmo Platform instance.

To get the URL for your Frosmo Platform instance:

Log in to the Frosmo Control Panel, and select your site.
In the header, click your username, and select API Access.
In the Product API section, copy the URL.

Authentication

The Product API does not require authentication.

Methods

The Product API supports the following standard HTTP methods:

GET
POST

The only difference between the two is that with GET you provide the product IDs in the request URL, while with POST you provide the product IDs in the request body. If your GET request URL exceeds the maximum URL length, use a POST request instead.

Syntax

GET

To retrieve product data using the GET method, make the following request:

GET
GET https://<platform_instance>/productApi?method=fetch&
    origin=<site_origin>&
    ids=["<product_1_id>","<product_2_id>","<product_n_id>"]

POST

To retrieve product data using the POST method, make the following request:

POST
POST https://<platform_instance>/productApi?method=fetch&
     origin=<site_origin>

# REQUEST BODY

[
  "<product_1_id>",
  "<product_2_id>",
  "<product_n_id>"
]

Parameters

Query parameters for Product API requests
Parameter	Description	Type	Role	Example
`method`	Request type. The possible values are: `fetch` to retrieve product data using GET or POST	String	Required	`method=fetch`
`origin`	Site origin. To find out your site's origin, see Getting your site origin.	String	Required	`origin=shop_company_com`
`ids`	IDs of the products whose data you want to retrieve. note The array must not be empty (`[]`). info The API ignores empty values (`[""]`). info The `ids` query parameter is only required for GET requests. POST requests pass the array of IDs in the request body. The above rules nonetheless apply to both GET and POST requests.	Array of strings	Required (GET)	Retrieve the data for one product: `ids=["123"]` Retrieve the data for three products: `ids=["123","456","789"]`
`variants`	Define whether to also return the data for product variants. If a product has one or more variants, the API returns the full product data for each variant in the `variants` array property of the product object. The possible values are: `false`: Do not return product variant data. `true`: Return product variant data. The default value is `false`.	Boolean	Boolean	`variants=true`
`debug`	Define whether to return debugging information for the requested products. warning Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same. The debugging information for a product consists of the product ID and a message about the status of the associated product data. The possible values are: `false`: Do not return debugging information. `true`: Return debugging information. The default value is `false`.	Boolean	Boolean	`debug=true`

Request examples

Example: Retrieve the product data for three products (GET)
GET https://inpref.com/productApi?method=fetch&
    origin=shop_company_com&
    ids=["123","456","789"]

Example: Retrieve the product data for three products (POST)
POST https://inpref.com/productApi?method=fetch&
     origin=shop_company_com

# REQUEST BODY

["123","456","789"]

Example: Retrieve the product and product variant data for three products (POST)
POST https://inpref.com/productApi?method=fetch&
     origin=shop_company_com&
     variants=true

# REQUEST BODY

["123","456","789"]

Example: Retrieve the product data for three products with debugging information (POST)
POST https://inpref.com/productApi?method=fetch&
     origin=shop_company_com&
     debug=true

# REQUEST BODY

["123","456","789"]

Responses

Success

On a success, the Product API returns the requested product data in the JSON format. The response status code is 200.

The response body is an object that contains the data array. Each item in the data array is an object that stores the data for a single product.

{
  "data": [
    {<product 1 data>},
    {<product 2 data>},
    ...
    {<product n data>}
  ]
}

Each product object contains the full set of product data tracked for the product on the site. The main product attributes (id, type, name, created_at, updated_at) are direct properties of the object, while all other product attributes are stored as properties of the attributes object.

# PRODUCT OBJECT

{
  "data": [
    {
      "id": "123",
      "type": "Food/Fruits",
      "name": "Coconut",
      "created_at": "2021-06-08T13:25:06+03:00",
      "updated_at": "2021-06-08T13:59:08+03:00",
      "attributes": {
        "availability": "in stock",
        "brand": "Mr. Fruit",
        "image": "https://company.com/images/products/product-123.png",
        "originalPrice": 5,
        "price": 3,
        "url": "https://company.com/products/123"
      }
    }
  ]
}

If a product is a parent product with one or more product variants, and if the request is set to also return variants, the product object includes the variants array, which contains the full product data for each variant.

# PRODUCT OBJECT WITH PRODUCT VARIANTS

{
  "data": [
    {
      "id": "1001",
      "type": "Fashion/Shoes",
      "name": "Casual Engineer Boots",
      "created_at": "2022-01-14T17:36:37+02:00",
      "updated_at": "2022-01-14T17:36:37+02:00",
      "attributes": {
        "availability": "in stock",
        "brand": "Lumberland",
        "color": "Black",
        "image": "https://shop.company.com/images/products/product-1001.png",
        "originalPrice": 350,
        "price": 290,
        "url": "https://shop.company.com/products/1001"
      },
      "variants": [
        {
          "id": "1002",
          "type": "Fashion/Shoes",
          "name": "Casual Engineer Boots",
          "created_at": "2022-01-14T17:36:37+02:00",
          "updated_at": "2022-01-14T17:36:37+02:00",
          "attributes": {
            "availability": "in stock",
            "brand": "Lumberland",
            "color": "Brown",
            "image": "https://shop.company.com/images/products/product-1002.png",
            "originalPrice": 350,
            "price": 290,
            "url": "https://shop.company.com/products/1002"
          }
        },
        {
          "id": "1003",
          "type": "Fashion/Shoes",
          "name": "Casual Engineer Boots",
          "created_at": "2022-01-14T17:36:37+02:00",
          "updated_at": "2022-01-14T17:36:37+02:00",
          "attributes": {
            "availability": "in stock",
            "brand": "Lumberland",
            "color": "White",
            "image": "https://shop.company.com/images/products/product-1003.png",
            "originalPrice": 350,
            "price": 290,
            "url": "https://shop.company.com/products/1003"
          }
        }
      ]
    }
  ]
}

Legacy product data

If you're tracking products using the legacy product data structure, which is now deprecated, note the following about the returned data:

The contents of the data and promotionLabel attributes are flattened on to the attributes object.
The data and promotionLabel attributes are also retained as properties of the attributes object.
If the data and promotionLabel attributes contain a property with the same name, only the property from data gets flattened on to attributes.

# data and promotionLabel both contain discountPrice

"attributes": {
  "data": "{\"onSale\":true,\"discountPrice\":10}",
  "promotionLabel": "{\"discountPrice\":13,\"color\":\"red\"}",
  "onSale": true,
  "discountPrice": 10,
  "color": "red"
}

# data and promotionLabel do not contain overlapping properties

"attributes": {
  "data": "{\"onSale\":true}",
  "promotionLabel": "{\"discountPrice\":13,\"color\":\"red\"}",
  "onSale": true
  "discountPrice": 13,
  "color": "red",
}

Error

On an error, the Product API returns the response status code 400 and an error message.

Product API error messages
Error message	Description	Solution
`parameter 'method' missing`	The `method` query parameter is missing from the request URL or its value is empty.	Make sure the `method` query parameter is properly defined.
`invalid method '<parameter_value>'`	The value of the `method` query parameter, `<parameter_value>`, is invalid.	Use `fetch` as the value of the `method` query parameter.
`parameter 'origin' missing`	The `origin` query parameter is missing from the request URL or its value is empty.	Make sure the `origin` query parameter is properly defined.
`invalid origin parameter '<parameter_value>'`	The value of the `origin` query parameter, `<parameter_value>`, is invalid.	Use a valid site origin as the value of the `origin` query parameter. To find out your site's origin, see Getting your site origin.
`parameter 'ids' missing`	The `ids` query parameter is missing from the request URL or its value is empty.	Make sure the `ids` query parameter is properly defined.
`parameter 'ids' contains invalid JSON: failed to parse`	The value of the `ids` query parameter is not a valid JSON array of strings.	Use a valid JSON array of strings as the value of the `ids` query parameter. Example `ids=["123","456","789"]`
`must provide at least one product id`	The value of the `ids` query parameter is an empty array.	Define at least one product ID in the `ids` parameter. Example `ids=["123"]`
`parameter 'variants' invalid, expected either 'true', 'false', '1' or '0'`	The value of the `variants` query parameter is invalid.	If you want to return product variant data, set the `variants` query parameter to either `true` or `1`. If you do not want to return product variant data, set the `variants` query parameter to either `false` or `0`, or omit the parameter from the request URL.

Requests​

URL​

Authentication​

Methods​

Syntax​

GET​

POST​

Parameters​

Request examples​

Responses​

Success​

Legacy product data​

Error​