{
    "openapi": "3.1.0",
    "info": {
        "title": "WEAZYO — store for AI agents",
        "version": "1",
        "description": "Read the product catalogue of WEAZYO and prepare a cart for a person. Agents never place orders or pay: build a cart link (GET /store/cart_link?items=...) and give it to the person. They review it, add it to their own cart with one button, sign in or create an account and check out themselves."
    },
    "servers": [
        {
            "url": "https://myshoptr.weazyo.com"
        }
    ],
    "paths": {
        "/store/catalog.json": {
            "get": {
                "operationId": "listProducts",
                "summary": "Search and list the products for sale",
                "description": "Public products only, paged. Follow `next` for the next page. The `checkout` block explains the cart link; `store.returns` the return policy (null when the store has not stated one).",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Words to search in titles and descriptions",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "description": "A category id from `categories`",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "description": "Leave out for A–Z by name",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "price_asc",
                                "price_desc",
                                "newest"
                            ]
                        }
                    },
                    {
                        "name": "min_price",
                        "in": "query",
                        "description": "Lowest unit price, in the catalogue currency",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        }
                    },
                    {
                        "name": "max_price",
                        "in": "query",
                        "description": "Highest unit price, in the catalogue currency",
                        "schema": {
                            "type": "number",
                            "minimum": 0
                        }
                    },
                    {
                        "name": "in_stock",
                        "in": "query",
                        "description": "1 = only products that can be ordered now (not sold out)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of products",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "store": {
                                            "type": "object"
                                        },
                                        "checkout": {
                                            "type": "object"
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "pages": {
                                            "type": "integer"
                                        },
                                        "next": {
                                            "type": [
                                                "string",
                                                "null"
                                            ],
                                            "format": "uri"
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "integer"
                                                    },
                                                    "title": {
                                                        "type": "string"
                                                    },
                                                    "products": {
                                                        "type": "integer"
                                                    }
                                                }
                                            }
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Product"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/store/cart_link": {
            "get": {
                "operationId": "cartLink",
                "summary": "A prepared cart, as a page for the person",
                "description": "Do not fetch this to buy: build the URL and give it to the person you shop for. The page lists the lines with prices and stock problems; nothing goes into a cart until the person presses the button. At most 50 products; repeated ids are added together; quantities above the stock are lowered.",
                "parameters": [
                    {
                        "name": "items",
                        "in": "query",
                        "required": true,
                        "description": "Comma-separated `id:quantity` pairs; the quantity defaults to 1",
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d+(:\\d+)?(,\\d+(:\\d+)?)*$",
                            "examples": [
                                "12:2,15"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "An HTML page for the person",
                        "content": {
                            "text/html": {}
                        }
                    }
                }
            }
        },
        "/store/cart_link.json": {
            "get": {
                "operationId": "checkCart",
                "summary": "Check and price a cart before giving the link",
                "description": "The same items value as /store/cart_link, answered as JSON: each line priced with its tax, the total, and the lines that will not go through (not in the store, sold out, quantity lowered to the stock). Use the returned cart_link: it keeps only what can be ordered. Nothing is put in a cart.",
                "parameters": [
                    {
                        "name": "items",
                        "in": "query",
                        "required": true,
                        "description": "Comma-separated `id:quantity` pairs",
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d+(:\\d+)?(,\\d+(:\\d+)?)*$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The checked cart",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "orderable": {
                                            "type": "boolean"
                                        },
                                        "cart_link": {
                                            "type": [
                                                "string",
                                                "null"
                                            ],
                                            "format": "uri"
                                        },
                                        "currency": {
                                            "type": "string"
                                        },
                                        "lines": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "subtotal": {
                                            "type": "string"
                                        },
                                        "taxes": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "percent": {
                                                        "type": "number"
                                                    },
                                                    "amount": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        },
                                        "total": {
                                            "type": "string"
                                        },
                                        "problems": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/store/feed.xml": {
            "get": {
                "operationId": "productFeed",
                "summary": "The same products as a Google Merchant / Meta product feed",
                "responses": {
                    "200": {
                        "description": "RSS 2.0 with the g: namespace",
                        "content": {
                            "application/xml": {}
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Product": {
                "type": "object",
                "required": [
                    "id",
                    "title",
                    "url",
                    "price",
                    "currency",
                    "availability",
                    "can_order",
                    "cart_link"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Product id, used in cart links"
                    },
                    "title": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string",
                        "description": "Plain text, at most 1000 characters"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "The product page"
                    },
                    "llms_txt": {
                        "type": "string",
                        "format": "uri"
                    },
                    "images": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "price": {
                        "type": "string",
                        "description": "Unit price before tax, two decimals",
                        "examples": [
                            "49.00"
                        ]
                    },
                    "currency": {
                        "type": "string",
                        "description": "ISO 4217"
                    },
                    "price_display": {
                        "type": "string"
                    },
                    "unit": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "category": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "category_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "brand": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "availability": {
                        "type": "string",
                        "enum": [
                            "InStock",
                            "OutOfStock",
                            "PreOrder",
                            "Discontinued"
                        ]
                    },
                    "can_order": {
                        "type": "boolean"
                    },
                    "stock": {
                        "type": "integer",
                        "description": "Units left, only when the store tracks and shows stock"
                    },
                    "sku": {
                        "type": "string"
                    },
                    "gtin": {
                        "type": "string"
                    },
                    "cart_link": {
                        "type": "string",
                        "format": "uri",
                        "description": "A cart link for one unit of this product"
                    }
                }
            }
        }
    }
}