{
  "openapi": "3.1.0",
  "info": {
    "title": "Storationship Storefront API",
    "version": "2026-10-28",
    "summary": "Public, unauthenticated read and cart endpoints of the Storationship online store (Shopify).",
    "description": "Storationship (https://storationship.com) sells conversation card games. The store runs on Shopify; this document describes the public storefront JSON endpoints that any browser or agent can call without credentials. Prices are in THB and returned as strings (e.g. \"849.00\") in the .json endpoints and as integers in satang (e.g. 84900) in the .js endpoints. Cart endpoints are scoped to the caller's cart cookie. Checkout and payment must be completed by the buyer: use the Universal Commerce Protocol (UCP) profile at /.well-known/ucp and its MCP endpoint for agent-driven carts and checkout, and see /llms.txt for agent guidelines. Orders must only be placed with the buyer's explicit authorization. Errors on cart endpoints are returned as JSON (see the Error schema). These endpoints are unversioned; breaking changes follow Shopify's storefront behavior.",
    "contact": {
      "name": "Storationship",
      "url": "https://storationship.com/pages/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://storationship.com/policies/terms-of-service"
    }
  },
  "externalDocs": {
    "description": "Agent instructions (Shop skill, UCP, WebMCP)",
    "url": "https://storationship.com/llms.txt"
  },
  "servers": [
    {
      "url": "https://storationship.com"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Store",
      "description": "Store metadata"
    },
    {
      "name": "Catalog",
      "description": "Products and collections (read-only)"
    },
    {
      "name": "Cart",
      "description": "Session cart, scoped to the cart cookie returned by the store"
    },
    {
      "name": "Agents",
      "description": "Agent commerce discovery"
    }
  ],
  "paths": {
    "/meta.json": {
      "get": {
        "tags": [
          "Store"
        ],
        "operationId": "getStoreMeta",
        "summary": "Store metadata (name, currency, country, description)",
        "responses": {
          "200": {
            "description": "Store metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreMeta"
                }
              }
            }
          }
        }
      }
    },
    "/products.json": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listProducts",
        "summary": "List published products",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/page"
          }
        ],
        "responses": {
          "200": {
            "description": "Products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{handle}.json": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "getProduct",
        "summary": "Get one product by handle",
        "parameters": [
          {
            "$ref": "#/components/parameters/productHandle"
          }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No product with this handle"
          }
        }
      }
    },
    "/products/{handle}.js": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "getProductAjax",
        "summary": "Get one product by handle (AJAX format, prices in satang, includes availability)",
        "parameters": [
          {
            "$ref": "#/components/parameters/productHandle"
          }
        ],
        "responses": {
          "200": {
            "description": "Product (served as text/javascript; body is JSON)",
            "content": {
              "text/javascript": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "No product with this handle"
          }
        }
      }
    },
    "/collections.json": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listCollections",
        "summary": "List published collections",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/page"
          }
        ],
        "responses": {
          "200": {
            "description": "Collections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "collections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Collection"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/collections/{handle}/products.json": {
      "get": {
        "tags": [
          "Catalog"
        ],
        "operationId": "listCollectionProducts",
        "summary": "List products in a collection (use handle \"all\" for every product)",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "all"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/page"
          }
        ],
        "responses": {
          "200": {
            "description": "Products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No collection with this handle"
          }
        }
      }
    },
    "/cart.js": {
      "get": {
        "tags": [
          "Cart"
        ],
        "operationId": "getCart",
        "summary": "Get the current cart",
        "responses": {
          "200": {
            "$ref": "#/components/responses/Cart"
          }
        }
      }
    },
    "/cart/add.js": {
      "post": {
        "tags": [
          "Cart"
        ],
        "operationId": "addToCart",
        "summary": "Add variants to the cart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "quantity"
                      ],
                      "properties": {
                        "id": {
                          "type": "integer",
                          "description": "Variant ID (products[].variants[].id)"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The added line items",
            "content": {
              "text/javascript": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "Variant unknown, unavailable or quantity not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cart/change.js": {
      "post": {
        "tags": [
          "Cart"
        ],
        "operationId": "changeCartLine",
        "summary": "Set the quantity of one cart line (0 removes it)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "quantity"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Variant ID or line item key"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Cart"
          },
          "422": {
            "description": "Invalid line or quantity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cart/update.js": {
      "post": {
        "tags": [
          "Cart"
        ],
        "operationId": "updateCart",
        "summary": "Set quantities for several variants, and the cart note/attributes",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "updates": {
                    "type": "object",
                    "description": "Map of variant ID to quantity",
                    "additionalProperties": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "note": {
                    "type": "string"
                  },
                  "attributes": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Cart"
          },
          "422": {
            "description": "Invalid line or quantity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cart/clear.js": {
      "post": {
        "tags": [
          "Cart"
        ],
        "operationId": "clearCart",
        "summary": "Remove every line from the cart",
        "responses": {
          "200": {
            "$ref": "#/components/responses/Cart"
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "getUcpProfile",
        "summary": "Universal Commerce Protocol profile (MCP endpoint, capabilities, payment handlers) for agent checkout",
        "externalDocs": {
          "url": "https://ucp.dev"
        },
        "responses": {
          "200": {
            "description": "UCP profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 250,
          "default": 30
        }
      },
      "page": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "productHandle": {
        "name": "handle",
        "in": "path",
        "required": true,
        "description": "Product handle (products[].handle)",
        "schema": {
          "type": "string"
        },
        "example": "storationship-x-the-shock-premium-set"
      }
    },
    "responses": {
      "Cart": {
        "description": "Cart (served as text/javascript; body is JSON, amounts in satang)",
        "content": {
          "text/javascript": {
            "schema": {
              "$ref": "#/components/schemas/Cart"
            }
          }
        }
      }
    },
    "schemas": {
      "StoreMeta": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "province": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "example": "THB"
          },
          "domain": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "body_html": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "vendor": {
            "type": "string"
          },
          "product_type": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "variants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Variant"
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Use as items[].id in /cart/add.js"
          },
          "product_id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "price": {
            "type": "string",
            "description": "THB, e.g. \"849.00\""
          },
          "compare_at_price": {
            "type": [
              "string",
              "null"
            ]
          },
          "requires_shipping": {
            "type": "boolean"
          },
          "taxable": {
            "type": "boolean"
          },
          "grams": {
            "type": "integer"
          },
          "position": {
            "type": "integer"
          },
          "option1": {
            "type": [
              "string",
              "null"
            ]
          },
          "option2": {
            "type": [
              "string",
              "null"
            ]
          },
          "option3": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Collection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "products_count": {
            "type": "integer"
          }
        }
      },
      "Cart": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "item_count": {
            "type": "integer"
          },
          "total_price": {
            "type": "integer",
            "description": "Satang (THB x 100)"
          },
          "currency": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Error body returned by the storefront as application/json",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "integer",
            "example": 422
          },
          "message": {
            "type": "string",
            "example": "Cart Error"
          },
          "description": {
            "type": "string",
            "example": "Cannot find variant"
          }
        }
      }
    }
  }
}
