Pages

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:

  1. In the Frosmo Control Panel, select Utilities > Frosmo APIs.
  2. In the Product API section, copy the URL.

    URL for Product API requests

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

Table: Query parameters for Product API requests

ParameterDescriptionTypeRoleExample
method

Request type.

The possible values are:

  • fetch to retrieve product data using GET or POST
StringRequired
method=fetch
origin

Site origin.

To find out your site's origin, see Getting your site origin.

StringRequired
origin=shop_company_com
ids

IDs of the products whose data you want to retrieve.

The array must not be empty ([]).

The API ignores empty values ([""]).

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 stringsRequired (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.

BooleanBoolean
variants=true
debug

Define whether to return debugging information for the requested products.

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.

BooleanBoolean
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.

Table: Product API error messages

Error messageDescriptionSolution
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.