{ "openapi": "3.0.1", "info": { "title": "scango.ch API", "description": "Customer REST API for scango.ch.\n\nAuthenticate with `Authorization: Bearer ` (Read or Write). Money amounts are integer cents. List responses use `{ data, meta }`.", "version": "1.0.0", "contact": { "name": "scango.ch Support", "email": "support@scango.ch", "url": "https://scango.ch" } }, "tags": [ { "name": "Products", "description": "Product catalog" }, { "name": "Orders", "description": "Orders" }, { "name": "Suppliers", "description": "Suppliers" }, { "name": "Categories", "description": "Categories" }, { "name": "Stores", "description": "Store locations" } ], "servers": [ { "url": "https://dashboard.scango.ch/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/products": { "get": { "tags": [ "Products" ], "summary": "List or search products", "operationId": "listProducts", "description": "List products, or search with `q`. Search supports `offset` and caps page size at 250. Without `q`, use `cursor` for stable pagination with `limit`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text. Enables `offset` pagination.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1\u20135000, default 100; max 250 with `q`).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip search hits. Only with `q`.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "store", "in": "query", "required": false, "description": "Filter by store id. Works with and without `q`. When set, `meta.total` reflects the filtered page (not the unfiltered search estimate).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque document id for the next page. Only without `q`. Do not parse. Follow `meta.nextCursor` until it is absent.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of products with meta.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "examples": { "fullCatalog": { "summary": "Catalog page (no search)", "value": { "data": [ { "id": "a1b2c3", "name": "Mineral water 50cl", "price": 120, "barcode": "7610800001234", "taxCategory": "2.6", "category": "cat_01", "supplier": "sup_01", "showOnScreen": true } ], "meta": { "total": 1, "returned": 1, "limit": 100, "nextCursor": "a1b2c3" } } }, "searchResults": { "summary": "Search with q", "value": { "data": [ { "id": "a1b2c3", "name": "Mineral water 50cl", "price": 120, "barcode": "7610800001234", "taxCategory": "2.6" } ], "meta": { "total": 42, "returned": 20, "limit": 20, "offset": 0 } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Search unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringError" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create product", "operationId": "createProduct", "description": "Create a product. Requires a Write key.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" }, "example": { "name": "Orange juice 1L", "price": 349, "taxCategory": "2.6", "description": "Fresh orange juice", "supplier": "sup_01", "category": "cat_beverages", "barcode": "7610800009999", "externalId": "sku-oj-1l", "showOnScreen": true, "ageRestriction": false, "showOnScale": false, "saleStop": false } } } }, "responses": { "200": { "description": "Product created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "id" ], "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } }, "example": { "success": true, "id": "newProductId" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/products/{productId}": { "get": { "tags": [ "Products" ], "summary": "Get product by ID", "operationId": "getProduct", "description": "Get a product by id.", "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Product" } } }, "example": { "data": { "id": "a1b2c3", "name": "Mineral water 50cl", "price": 120, "barcode": "7610800001234", "taxCategory": "2.6", "category": "cat_01", "supplier": "sup_01", "description": "", "showOnScreen": true, "ageRestriction": false, "showOnScale": false, "saleStop": false, "imageUrl": "" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Update product", "operationId": "updateProduct", "description": "Update a product (POST body is partial). Requires a Write key.", "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" }, "example": { "price": 129, "saleStop": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Products" ], "summary": "Delete product", "operationId": "deleteProduct", "description": "Soft-deletes a product. Requires a Write key.", "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Soft-deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "operationId": "listOrders", "description": "List orders. Requires `start`, `end`, and `paymentState`. Newest first. Use `limit` and optional `cursor` for pagination.", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Start of range (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": true, "description": "End of range (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "paymentState", "in": "query", "required": true, "description": "Payment status filter.", "schema": { "type": "string", "enum": [ "successful", "cancelled", "timeout", "failed", "pending" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1\u20135000, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque document id for the next page. Do not parse. Follow `meta.nextCursor` until it is absent.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Orders with meta", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "id": "order_01", "orderId": "order_01", "store": "store_01", "price": 4590, "paymentState": "successful", "orderDate": "2024-04-20T12:00:00.000Z", "transactionDate": "2024-04-20T12:00:01.000Z", "products": [] } ], "meta": { "total": 1, "returned": 1, "limit": 100, "nextCursor": "order_02" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/orders/{orderId}": { "get": { "tags": [ "Orders" ], "summary": "Get order by ID", "operationId": "getOrder", "description": "Get an order by id, including line items.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } }, "example": { "data": { "id": "order_01", "orderId": "order_01", "store": "store_01", "price": 240, "paymentState": "successful", "paymentMethod": "card", "paymentBrand": "visa", "orderDate": "2024-04-20T12:00:00.000Z", "transactionDate": "2024-04-20T12:00:01.000Z", "transactionMessage": "", "giftcardId": "", "products": [ { "productId": "a1b2c3", "quantity": 2, "title": "Mineral water 50cl", "price": 240, "netPrice": 226, "tax": 14, "taxRate": 2.6, "type": "product", "supplier": "sup_01", "category": "cat_01", "deposit": 0 } ] } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/suppliers": { "get": { "tags": [ "Suppliers" ], "summary": "List suppliers", "operationId": "listSuppliers", "description": "List suppliers.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1\u20135000, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Suppliers with meta", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "id": "sup_01", "name": "Example supplier", "company": "Example AG", "city": "Z\u00fcrich", "email": "orders@example.ch", "organizationId": "org_01" } ], "meta": { "total": 1, "returned": 1, "limit": 100 } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Suppliers" ], "summary": "Create supplier", "operationId": "createSupplier", "description": "Create a supplier. Requires a Write key.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreate" }, "example": { "name": "Example AG", "company": "Example AG", "city": "Zürich", "street": "Bahnhofstrasse 1", "plz": "8001", "email": "orders@example.ch" } } } }, "responses": { "200": { "description": "Supplier created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "id" ], "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } }, "example": { "success": true, "id": "newSupplierId" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/suppliers/{supplierId}": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier by ID", "operationId": "getSupplier", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Supplier details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Supplier" } } }, "example": { "data": { "id": "sup_01", "name": "Example supplier", "company": "Example AG", "city": "Z\u00fcrich", "street": "Bahnhofstrasse 1", "plz": "8001", "email": "orders@example.ch", "organizationId": "org_01" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Get a supplier by id." }, "post": { "tags": [ "Suppliers" ], "summary": "Update supplier", "operationId": "updateSupplier", "description": "Update a supplier (POST body is partial). Requires a Write key.", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierUpdate" }, "example": { "city": "Bern" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Suppliers" ], "summary": "Delete supplier", "operationId": "deleteSupplier", "description": "Soft-deletes a supplier. Requires a Write key.", "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Soft-deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/categories": { "get": { "tags": [ "Categories" ], "summary": "List categories", "operationId": "listCategories", "description": "List categories.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1\u20135000, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Categories with meta", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "id": "cat_01", "name": "Beverages", "index": 1, "showOnScreen": true } ], "meta": { "total": 1, "returned": 1, "limit": 100 } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Categories" ], "summary": "Create category", "operationId": "createCategory", "description": "Create a category. Requires a Write key.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" }, "example": { "name": "Beverages", "index": 1, "showOnScreen": true } } } }, "responses": { "200": { "description": "Category created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "id" ], "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } }, "example": { "success": true, "id": "newCategoryId" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/categories/{categoryId}": { "get": { "tags": [ "Categories" ], "summary": "Get category by ID", "operationId": "getCategory", "parameters": [ { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Category details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Category" } } }, "example": { "data": { "id": "cat_01", "name": "Beverages", "index": 1, "showOnScreen": true, "imageUrl": "" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Get a category by id." }, "post": { "tags": [ "Categories" ], "summary": "Update category", "operationId": "updateCategory", "description": "Update a category (POST body is partial). Requires a Write key. Empty `allowStore` or `hideStore` arrays remove the field.", "parameters": [ { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryUpdate" }, "example": { "index": 2 } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete category", "operationId": "deleteCategory", "description": "Soft-deletes a category. Requires a Write key.", "parameters": [ { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Soft-deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/stores": { "get": { "tags": [ "Stores" ], "summary": "List stores", "operationId": "listStores", "description": "List store locations. Use `city` as the human-readable label alongside `name`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1\u20135000, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stores with meta", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "id": "store_01", "name": "Main store", "city": "Z\u00fcrich", "address": "Bahnhofstrasse 1", "zipCode": "8001" } ], "meta": { "total": 1, "returned": 1, "limit": 100 } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Stores" ], "summary": "Create store", "operationId": "createStore", "description": "Create a store location. Requires a Write key. Within an organization, `name` is often the brand; use `city` (or address) to distinguish locations. Payment provider credentials (Zahls) are configured in the dashboard, not via this API.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCreate" }, "example": { "name": "Main store", "city": "Z\u00fcrich", "address": "Bahnhofstrasse 1", "zipCode": "8001" } } } }, "responses": { "200": { "description": "Store created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "id" ], "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } }, "example": { "success": true, "id": "newStoreId" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/stores/{storeId}": { "get": { "tags": [ "Stores" ], "summary": "Get store by ID", "operationId": "getStore", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Store details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Store" } } }, "example": { "data": { "id": "store_01", "name": "Main store", "city": "Z\u00fcrich", "address": "Bahnhofstrasse 1", "zipCode": "8001" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Get a store by id." }, "post": { "tags": [ "Stores" ], "summary": "Update store", "operationId": "updateStore", "description": "Update a store (POST body is partial). Requires a Write key. Send `null` to clear an optional field. Payment provider credentials (Zahls) remain dashboard-only.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUpdate" }, "example": { "city": "Bern" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Stores" ], "summary": "Delete store", "operationId": "deleteStore", "description": "Soft-deletes a store. Requires a Write key.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Soft-deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "Product": { "type": "object", "description": "Product. Money fields are integer cents.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Product document id" }, "externalId": { "type": "string", "description": "Optional external identifier" }, "name": { "type": "string" }, "price": { "type": "integer", "description": "Price in cents." }, "supplier": { "type": "string", "description": "Supplier id" }, "taxCategory": { "type": "string", "enum": [ "8.1", "2.6", "3.8", "0" ], "description": "Swiss VAT category code" }, "category": { "type": "string", "description": "Category id" }, "declarations": { "type": "string" }, "barcode": { "type": "string" }, "depositProduct": { "type": "integer", "description": "Deposit in cents." }, "depositProductLabel": { "type": "string" }, "description": { "type": "string" }, "salePrice": { "type": "integer", "description": "Sale price in cents." }, "salePercentage": { "type": "number" }, "salePriceDateFrom": { "type": "string", "format": "date-time" }, "salePriceDateTo": { "type": "string", "format": "date-time" }, "costPrice": { "type": "integer", "description": "Cost price in cents." }, "margin": { "type": "number" }, "showOnScreen": { "type": "boolean" }, "ageRestriction": { "type": "boolean" }, "showOnScale": { "type": "boolean" }, "saleStop": { "type": "boolean" }, "deactivated": { "type": "boolean" }, "openInput": { "type": "boolean" }, "imageUrl": { "type": "string", "description": "Image URL (read-only)." }, "index": { "type": "integer" }, "allowStore": { "type": "array", "items": { "type": "string" }, "description": "Allowed store ids (read-only)." }, "hideStore": { "type": "array", "items": { "type": "string" }, "description": "Hidden store ids (read-only)." }, "deleted": { "type": "boolean", "description": "Soft-deleted when true." }, "createdate": { "type": "string", "format": "date-time" }, "lastupdate": { "type": "string", "format": "date-time" }, "instance": { "type": "string", "description": "Organization id when present" } } }, "ProductCreate": { "type": "object", "required": [ "name", "price", "taxCategory" ], "description": "Create product body. Requires a Write key.", "properties": { "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents" }, "taxCategory": { "type": "string", "enum": [ "8.1", "2.6", "3.8", "0" ] }, "supplier": { "type": "string" }, "category": { "type": "string" }, "declarations": { "type": "string" }, "barcode": { "type": "string", "description": "Normalized to lowercase; empty becomes the document id" }, "externalId": { "type": "string" }, "depositProduct": { "type": "number", "description": "Deposit in cents" }, "depositProductLabel": { "type": "string" }, "description": { "type": "string" }, "salePrice": { "type": "number" }, "salePercentage": { "type": "number" }, "salePriceDateFrom": { "type": "string", "format": "date-time" }, "salePriceDateTo": { "type": "string", "format": "date-time" }, "costPrice": { "type": "number" }, "margin": { "type": "number" }, "showOnScreen": { "type": "boolean" }, "ageRestriction": { "type": "boolean" }, "showOnScale": { "type": "boolean" }, "saleStop": { "type": "boolean" }, "index": { "type": "number" } } }, "ProductUpdate": { "type": "object", "description": "Partial update body (POST). Requires a Write key.", "properties": { "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents" }, "taxCategory": { "type": "string", "enum": [ "8.1", "2.6", "3.8", "0" ] }, "supplier": { "type": "string" }, "category": { "type": "string" }, "declarations": { "type": "string" }, "barcode": { "type": "string", "description": "Normalized to lowercase; empty becomes the document id" }, "externalId": { "type": "string" }, "depositProduct": { "type": "number", "description": "Deposit in cents" }, "depositProductLabel": { "type": "string" }, "description": { "type": "string" }, "salePrice": { "type": "number" }, "salePercentage": { "type": "number" }, "salePriceDateFrom": { "type": "string", "format": "date-time" }, "salePriceDateTo": { "type": "string", "format": "date-time" }, "costPrice": { "type": "number" }, "margin": { "type": "number" }, "showOnScreen": { "type": "boolean" }, "ageRestriction": { "type": "boolean" }, "showOnScale": { "type": "boolean" }, "saleStop": { "type": "boolean" }, "index": { "type": "number" }, "deleted": { "type": "boolean", "description": "Set true to soft-delete." } } }, "CategoryCreate": { "type": "object", "required": [ "name" ], "description": "Create category body. Requires a Write key.", "properties": { "name": { "type": "string" }, "index": { "type": "number" }, "showOnScreen": { "type": "boolean" }, "imageUrl": { "type": "string" }, "marginMinPercent": { "type": "number" }, "marginMaxPercent": { "type": "number" }, "hideStore": { "type": "array", "items": { "type": "string" } }, "allowStore": { "type": "array", "items": { "type": "string" } } } }, "CategoryUpdate": { "type": "object", "description": "Partial update body (POST). Requires a Write key. Empty `allowStore` or `hideStore` arrays remove the field.", "properties": { "name": { "type": "string" }, "index": { "type": "number" }, "showOnScreen": { "type": "boolean" }, "imageUrl": { "type": "string" }, "marginMinPercent": { "type": "number" }, "marginMaxPercent": { "type": "number" }, "hideStore": { "type": "array", "items": { "type": "string" }, "description": "Empty array removes the field." }, "allowStore": { "type": "array", "items": { "type": "string" }, "description": "Empty array removes the field." }, "deleted": { "type": "boolean", "description": "Set true to soft-delete." } } }, "SupplierCreate": { "type": "object", "required": [ "name" ], "description": "Create supplier body. Requires a Write key.", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "plz": { "type": "string" }, "email": { "type": "string" }, "payoutEmail": { "type": "string" }, "orderEmail": { "type": "string" }, "phone": { "type": "string" }, "contactPerson": { "type": "string" }, "contactPhone": { "type": "string" }, "dailyMail": { "type": "string" }, "supplierMargin": { "type": "number" }, "iban": { "type": "string" }, "bic": { "type": "string" }, "bankName": { "type": "string" }, "payoutsEnabled": { "type": "boolean" } } }, "SupplierUpdate": { "type": "object", "description": "Partial update body (POST). Requires a Write key.", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "plz": { "type": "string" }, "email": { "type": "string" }, "payoutEmail": { "type": "string" }, "orderEmail": { "type": "string" }, "phone": { "type": "string" }, "contactPerson": { "type": "string" }, "contactPhone": { "type": "string" }, "dailyMail": { "type": "string" }, "supplierMargin": { "type": "number" }, "iban": { "type": "string" }, "bic": { "type": "string" }, "bankName": { "type": "string" }, "payoutsEnabled": { "type": "boolean" }, "deleted": { "type": "boolean", "description": "Set true to soft-delete." } } }, "Order": { "type": "object", "additionalProperties": false, "description": "Order. Dates are ISO-8601. Money fields are integer cents.", "properties": { "id": { "type": "string", "description": "Id" }, "orderId": { "type": "string" }, "orderDate": { "type": "string", "format": "date-time" }, "transactionDate": { "type": "string", "format": "date-time" }, "paymentMethod": { "type": "string" }, "paymentState": { "type": "string", "enum": [ "successful", "cancelled", "timeout", "failed", "pending" ] }, "paymentBrand": { "type": "string" }, "price": { "type": "integer", "description": "Order total in cents" }, "store": { "type": "string", "description": "Store id" }, "transactionMessage": { "type": "string" }, "giftcardId": { "type": "string" }, "giftcardFunction": { "type": "string" }, "deleted": { "type": "boolean" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } } } }, "OrderLine": { "type": "object", "additionalProperties": false, "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "price": { "type": "integer", "description": "Line total in cents." }, "netPrice": { "type": "integer", "description": "Net amount in cents." }, "deposit": { "type": "integer", "description": "Deposit in cents." }, "costPrice": { "type": "integer" }, "quantity": { "type": "number" }, "weight": { "type": "number" }, "supplier": { "type": "string" }, "category": { "type": "string" }, "tax": { "type": "integer", "description": "Tax amount in cents." }, "taxRate": { "type": "number" }, "type": { "type": "string", "description": "e.g. product, coupon, giftcard." }, "imageUrl": { "type": "string" }, "originalProductId": { "type": "string" }, "originalPrice": { "type": "integer" }, "discount": { "type": "number" }, "undiscountedPrice": { "type": "integer" }, "store": { "type": "string" }, "printTicket": { "type": "boolean" } } }, "Supplier": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "plz": { "type": "string" }, "organizationId": { "type": "string" }, "email": { "type": "string" }, "payoutEmail": { "type": "string" }, "orderEmail": { "type": "string" }, "phone": { "type": "string" }, "contactPerson": { "type": "string" }, "contactPhone": { "type": "string" }, "dailyMail": { "type": "string" }, "deleted": { "type": "boolean" }, "supplierMargin": { "type": "number" }, "iban": { "type": "string" }, "bic": { "type": "string" }, "bankName": { "type": "string" }, "payoutsEnabled": { "type": "boolean" }, "createdate": { "type": "string", "format": "date-time" } } }, "Category": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "index": { "type": "integer" }, "showOnScreen": { "type": "boolean" }, "imageUrl": { "type": "string" }, "marginMinPercent": { "type": "number" }, "marginMaxPercent": { "type": "number" }, "deleted": { "type": "boolean" }, "hideStore": { "type": "array", "items": { "type": "string" } }, "allowStore": { "type": "array", "items": { "type": "string" } }, "createdate": { "type": "string", "format": "date-time" } } }, "ListMeta": { "type": "object", "required": [ "total", "returned", "limit" ], "description": "List metadata. `returned` is the length of `data`. Soft-deleted catalog rows are omitted from list results, so `returned` may be less than `limit` even when more active items exist. When `nextCursor` is present, more pages may exist — keep paging until `nextCursor` is absent.", "properties": { "total": { "type": "integer", "description": "With product search (`q`) without `store`: estimated match count. With `store`: equals `returned` after store visibility filtering. Otherwise equals `returned`. Soft-deleted items are omitted, so a page may be shorter than `limit` even when more active items exist." }, "returned": { "type": "integer", "description": "Number of active items in `data` (soft-deleted rows excluded)." }, "limit": { "type": "integer", "description": "Applied page size." }, "offset": { "type": "integer", "description": "Only for product search with `q`." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Present when more results may exist. Do not parse; pass unchanged as `cursor`. Under soft-delete filtering, `returned < limit` does not mean the list is finished." } } }, "ValidationError": { "type": "object", "description": "Validation details.", "required": [ "formErrors", "fieldErrors" ], "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "ValidationErrorResponse": { "type": "object", "description": "Validation error response.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ValidationError" } } }, "ErrorEnvelope": { "type": "object", "required": [ "statusCode", "message", "timestamp", "path" ], "description": "Error response.", "properties": { "statusCode": { "type": "integer", "description": "HTTP status code" }, "message": { "type": "string", "description": "Human-readable error message" }, "timestamp": { "type": "string", "format": "date-time" }, "path": { "type": "string", "description": "Request path" } } }, "StringError": { "type": "object", "description": "Simple error response.", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Error": { "description": "Error response.", "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/StringError" } ] }, "StoreCreate": { "type": "object", "required": [ "name" ], "description": "Create store body. Requires a Write key. Within an organization, `name` is often the brand; use `city` (or address) to distinguish locations. Payment provider credentials (Zahls) are configured in the dashboard.", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "zipCode": { "type": "string" }, "city": { "type": "string", "description": "Human-readable store label within the organization" }, "vatNumber": { "type": "string" }, "paymentCash": { "type": "boolean" }, "paymentPaytec": { "type": "boolean" }, "paymentZahls": { "type": "boolean" }, "paymentZahlsOffline": { "type": "boolean" }, "paymentCashOffline": { "type": "boolean" }, "showSupplier": { "type": "boolean" }, "hideTextStart": { "type": "boolean" }, "generalMargin": { "type": "number" }, "customMessage": { "type": "string" }, "backgroundImageCart": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "src": { "type": "string" } } } ] }, "backgroundImage": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "src": { "type": "string" } } } ] }, "backgroundColor": { "type": "string" }, "backgroundFontColor": { "type": "string" }, "playSound": { "type": "boolean" }, "standardSound": { "type": "string" }, "adminMail": { "type": "string" }, "showInfoButton": { "type": "boolean" }, "deleteCountdown": { "type": "number" }, "logoUrl": { "type": "string" }, "languageMulti": { "type": "boolean" }, "languageMain": { "type": "string", "enum": [ "de", "en", "fr", "it" ] }, "languageSelector": { "type": "array", "items": { "type": "string", "enum": [ "de", "en", "fr", "it" ] } }, "translations": { "type": "object", "additionalProperties": true } } }, "StoreUpdate": { "type": "object", "description": "Partial update body (POST). Requires a Write key. Send `null` to clear an optional field.", "properties": { "name": { "type": "string" }, "address": { "type": "string", "nullable": true }, "zipCode": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "description": "Human-readable store label within the organization" }, "vatNumber": { "type": "string", "nullable": true }, "paymentCash": { "type": "boolean", "nullable": true }, "paymentPaytec": { "type": "boolean", "nullable": true }, "paymentZahls": { "type": "boolean", "nullable": true }, "paymentZahlsOffline": { "type": "boolean", "nullable": true }, "paymentCashOffline": { "type": "boolean", "nullable": true }, "showSupplier": { "type": "boolean", "nullable": true }, "hideTextStart": { "type": "boolean", "nullable": true }, "generalMargin": { "type": "number", "nullable": true }, "customMessage": { "type": "string", "nullable": true }, "backgroundImageCart": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "src": { "type": "string" } } }, { "type": "null" } ] }, "backgroundImage": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "src": { "type": "string" } } }, { "type": "null" } ] }, "backgroundColor": { "type": "string", "nullable": true }, "backgroundFontColor": { "type": "string", "nullable": true }, "playSound": { "type": "boolean", "nullable": true }, "standardSound": { "type": "string", "nullable": true }, "adminMail": { "type": "string", "nullable": true }, "showInfoButton": { "type": "boolean", "nullable": true }, "deleteCountdown": { "type": "number", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "languageMulti": { "type": "boolean", "nullable": true }, "languageMain": { "type": "string", "enum": [ "de", "en", "fr", "it" ], "nullable": true }, "languageSelector": { "type": "array", "items": { "type": "string", "enum": [ "de", "en", "fr", "it" ] }, "nullable": true }, "translations": { "type": "object", "additionalProperties": true, "nullable": true }, "deleted": { "type": "boolean", "description": "Set true to soft-delete." } } }, "Store": { "type": "object", "additionalProperties": true, "description": "Store location. Payment integration secrets are never returned.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string", "description": "Human-readable store label within the organization" }, "address": { "type": "string" }, "zipCode": { "type": "string" }, "vatNumber": { "type": "string" }, "paymentCash": { "type": "boolean" }, "paymentPaytec": { "type": "boolean" }, "paymentZahls": { "type": "boolean" }, "paymentZahlsOffline": { "type": "boolean" }, "paymentCashOffline": { "type": "boolean" }, "showSupplier": { "type": "boolean" }, "logoUrl": { "type": "string" }, "languageMain": { "type": "string", "enum": [ "de", "en", "fr", "it" ] }, "deleted": { "type": "boolean" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Organization API key." } } } }