- Molin API integration specs
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',
});
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.
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.
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.
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.
Our API does not support http
connections. You must use https
to ensure that the data is encrypted in transit.
This API is similar to the webhooks system in other platforms such as Stripe. You must configure these endpoints in the molin.ai dashboard.
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
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": "john@example.com"
}
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.
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
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": "john@example.com"
}
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"
}
This spec describes a JSON API served via HTTP, using header-based authentication and the schema.org format for product data.
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.
We require the following endpoints if you are creating a custom API for us.
We need an endpoint that we can call frequently to download your products.
- 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)
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).
- name
- offers (so we can extract a price — must include price and priceCurrency)
- url (so we can uniquely identify the product)
- Image
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).
You may add header-based authentication that relies on a simple shared secret (token).
If you give us the token M123ABC
, we will include the following header in all requests:
Authorization: M123ABC
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!