This spec describes a JSON API served via HTTP, using header-based authentication and the schema.org format for product data.

​
Intro

We borrowed the JSON-LD spec because shops already use it. If you visit any product page hosted by Shopify you’ll find a type="application/ld+json" script tag encoding product information in a schema.org format.

​
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