Molin API integration specs

• Molin API integration specs
  • Example
  • Versioning
  • Schemas
  • Security
    • Sensitive information in responses
    • HMAC signature verification
    • Encryption
  • Webhooks API
    • Order Query
      • Request
      • Response
    • Order Cancellation
      • Request
      • Response
  • Product Sync API
    • Intro
    • Endpoints
      • Retrieving all products
        • Spec
        • Example
        • Mandatory fields
        • Optional but recommended fields
      • Retrieving 1 product
    • Authentication
      • Example
  • Custom Actions API

Example

npm install --save valibot # peer dependency

import { OrderCancellationResponseSchema } from '@molin.ai/api/v20240910.js';
import * as v from 'valibot';

v.parse(OrderCancellationResponseSchema, {
  cancelled: false,
  reason: 'Invalid order ID',
});

Versioning

Please note that the API is versioned. Whenever you configure a webhook via our dashboard, you will need to select a version. The version you select will determine the format of the request that Molin will send to you and the format of the response you must respond with.

Schemas

We use valibot schemas to validate the request and response payloads. We also publish these schemas via npm, so you can use them to validate the response payloads in your code. Using the npm package is optional as long as your implementation is compliant and follows the schemas documented below.

Unless a field is marked as optional using v.optional(), it is required and cannot be null/undefined. Generally, all top-level fields are required, nested fields may be optional, and you may provide additional data in the extra field.

Security

Sensitive information in responses

Do not include sensitive information in any response. You should assume that the response will be visible to the user in its entirety. If you need to include sensitive information, you should provide a link to a secure page where the user can view the information.

HMAC signature verification

We are working on implementing HMAC signatures on all requests so you can verify that the request is coming from Molin. This feature is not yet available, but we will update this document when it is.

Encryption

Our API does not support http connections. You must use https to ensure that the data is encrypted in transit.

Webhooks API

This API is similar to the webhooks system in other platforms such as Stripe. You must configure these endpoints in the molin.ai dashboard.

Order Query

Molin will send Order Query requests when a user requests information about an order. You should respond with the order details.

Example URL: https://store.com/webhook/molin/v20240910/order-query

Request

Method: POST

Schema:

const OrderQueryRequestSchema = v.object({
  widgetId: v.string(),
  conversationId: v.string(),
  orderId: v.string(),
  orderEmail: v.string(),
});

Example:

{
  "widgetId": "v0iyxl53",
  "conversationId": "2d326641-a872-4d7c-8306-9a42e6bd05ca",
  "orderId": "ex123",
  "orderEmail": "[email protected]"
}

Response

If the order is not found, you should respond with a 404 status code.

If found, you should respond with a 200 status code and the following body.

Schema:

const OrderQueryResponseSchema = v.object({
  status: v.string(),
  payment: v.object({
    method: v.optional(v.string()),
  }),
  shipping: v.object({
    method: v.optional(v.string()),
    trackingURL: v.optional(v.string()),
  }),
  customer: v.object({
    name: v.optional(v.string()),
    email: v.optional(v.string()),
  }),
  extra: v.any(),
});

Example:

{
  "status": "shipped",
  "payment": {
    "method": "credit card"
  },
  "shipping": {
    "method": "courier - DHL Express",
    "trackingURL": "https://dhl.com/track/123456"
  },
  "customer": {},
  "extra": {
    "expectedDeliveryDate": "2026-12-25"
  }
}

In general, strings should be human readable, but short and succinct.

Order Cancellation

Molin will send Order Cancellation requests when a user requests to cancel an order. You should respond with the status of the cancellation.

Example URL: https://store.com/webhook/molin/v20240910/order-cancellation

Request

Method: POST

Schema:

const OrderCancellationRequestSchema = v.object({
  widgetId: v.string(),
  conversationId: v.string(),
  orderId: v.string(),
  orderEmail: v.string(),
});

Example:

{
  "widgetId": "v0iyxl53",
  "conversationId": "2d326641-a872-4d7c-8306-9a42e6bd05ca",
  "orderId": "ex123",
  "orderEmail": "[email protected]"
}

Response

You should always respond with a 200 status code.

Schema:

const OrderCancellationResponseSchema = v.object({
  cancelled: v.boolean(),
  reason: v.optional(v.string()),
});

Examples:

{
  "cancelled": true
}

{
  "cancelled": false,
  "reason": "order not found / order already shipped"
}

Product Sync API

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, for example visit any product page hosted by Shopify and 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 us.

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 Product (schema.org)

Example

GET https://petshop.com/molin/products.json

[
  {
    "@context": "http://schema.org",
    "@type": "Product",
    "name": "Coffee Lenoa | Espresso",
    "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"
        }
      ]
    }
  }
]

The above response contains 1 product along with price and stock information.

Note: You don’t have to use an AggregateOffer, you can just return 1 offer (1 price).

Mandatory fields

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

Optional but recommended fields

• Image

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

Custom Actions API

We are working on an API that allows you to define custom actions that can be triggered by the user. For example, you could define an action that sends an email to the user with a discount code, when they request one. Stay tuned!