This spec describes a JSON API served via HTTP that uses Schema.org structured data format for product synchronization, with header-based authentication.

​
Intro

We chose the Schema.org format with JSON-LD spec because it’s the web standard for structured data that most e-commerce platforms already use. If you visit any product page hosted by Shopify, WooCommerce, or other major platforms, you’ll find a type="application/ld+json" script tag encoding product information in Schema.org format. This API leverages that same standardized structure to make product data integration seamless.

​
Endpoints

We require the following endpoints if you are creating a custom API for Molin.

​
Retrieving all products

We need an endpoint that we can call frequently to download your products.

​
Spec

  • Content-Type must be application/json
  • The body must contain a list of products encoded as a JSON string
  • Each product object must be of type schema.org/Product

​
Example

GET https://petshop.com/molin/products.json 
[
  {
    "@context": "http://schema.org",
    "@type": "Product",
    "name": "Coffee Lenoa | Espresso",
    "description": "The best coffee beans imported from...",
    "brand": "Coffee Lenoa",
    "image": "//lenoacoffeeandshop.hu/cdn/shop/files/...",
    "url": "https://lenoacoffeeandshop.hu/products/lenoa-espresso",
    "offers": {
      "@type": "AggregateOffer",
      "priceCurrency": "USD",
      "lowPrice": "12.99",
      "highPrice": "19.99",
      "itemCondition": "http://schema.org/New",
      "availability": "http://schema.org/InStock",
      "offerCount": "2",
      "offers": [
        {
          "@type": "Offer",
          "name": "Coffee Lenoa | Espresso — 1000 gramm",
          "availability": "http://schema.org/InStock",
          "priceCurrency": "USD",
          "price": "19.99"
        },
        {
          "@type": "Offer",
          "name": "Coffee Lenoa | Espresso — 250 gramm",
          "availability": "http://schema.org/InStock",
          "priceCurrency": "USD",
          "price": "12.99"
        }
      ]
    },
    "additionalProperty": [
      {
        "@type": "PropertyValue",
        "name": "Origin",
        "value": "Ethiopia"
      },
      {
        "@type": "PropertyValue",
        "name": "Roast Level",
        "value": "Medium"
      },
      {
        "@type": "PropertyValue",
        "name": "Caffeine Content",
        "value": "High"
      }
    ]
  }
]
The above response contains 1 product along with price and stock information.
You don’t have to use an schema.org/AggregateOffer, you can just return a single schema.org/Offer.

​
Mandatory fields

  • name
  • offers (so we can extract a price — must include price and priceCurrency)
  • url (so we can uniquely identify the product)
  • Image

​
Providing extra attributes

You can include additional product attributes using the additionalProperty field from the schema.org specification. This allows you to provide custom properties that aren’t part of the standard Product schema. The additionalProperty field accepts an array of PropertyValue objects, each containing:
  • name - The property name (e.g., “Origin”, “Material”, “Size”)
  • value - The property value (e.g., “Ethiopia”, “Cotton”, “Large”)

​
Example usage

"additionalProperty": [
  {
    "@type": "PropertyValue",
    "name": "Origin",
    "value": "Ethiopia"
  },
  {
    "@type": "PropertyValue",
    "name": "Roast Level",
    "value": "Medium"
  },
  {
    "@type": "PropertyValue",
    "name": "Caffeine Content",
    "value": "High"
  }
]
This is particularly useful for:
  • Product specifications (dimensions, materials, etc.)
  • Custom categorization
  • Brand-specific attributes
  • Technical details that customers might ask about
Molin uses these additional properties to provide more detailed and accurate responses about your products when customers ask specific questions.
There is a limit of 10 attributes per product. Molin will ignore any additional attributes beyond this limit.

​
Retrieving 1 product

This is an optimization that we have not built yet. If you have lots of products, it is more efficient to also offer a single product endpoint. For example, if a customer asks Molin about the stock of 1 specific product, we will update only this specific product (quicker than downloading all of them).

​
Authentication

You may add header-based authentication that relies on a simple shared secret (token).

​
Example

If you give us the token M123ABC, we will include the following header in all requests: 
Authorization: M123ABC