{
  "openapi": "3.1.0",
  "info": {
    "title": "Nordkauf Shop API",
    "version": "3.1.0",
    "description": "The Nordkauf Shop API powers storefronts and integrations: browse the catalog, manage carts, run checkouts and receive webhooks for orders and inventory.\n\nThis is a **fictional demo API** showcasing the docHQ documentation viewer."
  },
  "servers": [{ "url": "https://api-demo.nordkauf.example" }],
  "x-topics": [
    {
      "title": "Authentication",
      "content": "All requests must include your API key in the `X-Api-Key` header. Keys are issued per sales channel.\n\n| Environment | Base URL |\n|---|---|\n| Sandbox | `https://api-sandbox.nordkauf.example` |\n| Production | `https://api.nordkauf.example` |",
      "example": "Example request:\n\n```\ncurl https://api-demo.nordkauf.example/v1/products \\\n  -H \"X-Api-Key: ak_live_4f8a...\"\n```"
    },
    {
      "title": "Webhook Signature",
      "content": "Every webhook request is signed with an HMAC-SHA256 signature in the `X-Nordkauf-Signature` header. Verify it against your webhook secret before processing the payload.",
      "example": "```\nX-Nordkauf-Signature: sha256=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd\n```"
    },
    {
      "title": "Output Format",
      "content": "All endpoints return JSON. List endpoints are paginated with `filters[limit]` and `filters[offset]` and return a `pagination` object with the `total` count. Prices are integer amounts in the smallest currency unit (cents)."
    }
  ],
  "x-tagGroups": [
    { "name": "Catalog", "tags": ["Product", "Category"] },
    { "name": "Cart", "tags": ["Cart", "Cart Items"] },
    { "name": "Checkout", "tags": ["Order", "Payment"] },
    { "name": "Webhooks", "tags": ["Order Webhooks", "Inventory Webhooks"] }
  ],
  "paths": {
    "/v1/products": {
      "get": {
        "tags": ["Product"],
        "summary": "ListProducts",
        "description": "Get products as list. You can use different filter options.",
        "parameters": [
          { "name": "filters[limit]", "in": "query", "schema": { "type": "integer" } },
          { "name": "filters[offset]", "in": "query", "schema": { "type": "integer" } },
          { "name": "filters[categoryId]", "in": "query", "schema": { "type": "string" } },
          { "name": "filters[status]", "in": "query", "schema": { "type": "string", "enum": ["active", "draft", "archived"] } }
        ],
        "responses": {
          "200": { "description": "List of products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/products/{productId}": {
      "get": {
        "tags": ["Product"],
        "summary": "GetProduct",
        "parameters": [{ "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/categories": {
      "get": {
        "tags": ["Category"],
        "summary": "ListCategories",
        "responses": {
          "200": { "description": "Categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }
        }
      }
    },
    "/v1/carts": {
      "post": {
        "tags": ["Cart"],
        "summary": "CreateCart",
        "description": "Create an empty cart for a customer or guest session.",
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCartRequest" } } }
        },
        "responses": {
          "201": { "description": "Cart created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }
        }
      }
    },
    "/v1/carts/{cartId}": {
      "get": {
        "tags": ["Cart"],
        "summary": "GetCart",
        "parameters": [{ "name": "cartId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Cart with items and totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "delete": {
        "tags": ["Cart"],
        "summary": "DeleteCart",
        "parameters": [{ "name": "cartId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "204": { "description": "Deleted" } }
      }
    },
    "/v1/carts/{cartId}/items": {
      "post": {
        "tags": ["Cart Items"],
        "summary": "AddCartItem",
        "description": "Add a product variant to the cart. Adding the same variant twice increases the quantity.",
        "parameters": [{ "name": "cartId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCartItemRequest" } } }
        },
        "responses": {
          "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } },
          "409": { "description": "Out of stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/carts/{cartId}/items/{itemId}": {
      "patch": {
        "tags": ["Cart Items"],
        "summary": "UpdateCartItem",
        "description": "Change the quantity of a cart item. Quantity `0` removes the item.",
        "parameters": [
          { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCartItemRequest" } } }
        },
        "responses": {
          "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }
        }
      },
      "delete": {
        "tags": ["Cart Items"],
        "summary": "RemoveCartItem",
        "parameters": [
          { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }
        }
      }
    },
    "/v1/orders": {
      "get": {
        "tags": ["Order"],
        "summary": "ListOrders",
        "parameters": [
          { "name": "filters[limit]", "in": "query", "schema": { "type": "integer" } },
          { "name": "filters[status]", "in": "query", "schema": { "type": "string", "enum": ["pending", "paid", "shipped", "refunded", "cancelled"] } }
        ],
        "responses": {
          "200": { "description": "Orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }
        }
      },
      "post": {
        "tags": ["Order"],
        "summary": "CreateOrder",
        "description": "Convert a cart into an order (checkout).",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }
        },
        "responses": {
          "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } },
          "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/orders/{orderId}": {
      "get": {
        "tags": ["Order"],
        "summary": "GetOrder",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/orders/{orderId}/payments": {
      "post": {
        "tags": ["Payment"],
        "summary": "CapturePayment",
        "description": "Capture the payment for a pending order.",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapturePaymentRequest" } } }
        },
        "responses": {
          "201": { "description": "Payment captured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } },
          "402": { "description": "Payment failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/orders/{orderId}/refund": {
      "post": {
        "tags": ["Payment"],
        "summary": "RefundOrder",
        "description": "Refund a paid order, fully or partially.",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } }
        },
        "responses": {
          "201": { "description": "Refund created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }
        }
      }
    }
  },
  "webhooks": {
    "OrderPaid": {
      "post": {
        "tags": ["Order Webhooks"],
        "summary": "OrderPaid",
        "description": "An order was paid successfully.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaidEvent" } } }
        },
        "responses": { "200": { "description": "Acknowledge with HTTP 200." } }
      }
    },
    "OrderShipped": {
      "post": {
        "tags": ["Order Webhooks"],
        "summary": "OrderShipped",
        "description": "An order left the warehouse.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderShippedEvent" } } }
        },
        "responses": { "200": { "description": "Acknowledge with HTTP 200." } }
      }
    },
    "StockLow": {
      "post": {
        "tags": ["Inventory Webhooks"],
        "summary": "StockLow",
        "description": "The stock of a variant fell below its threshold.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockLowEvent" } } }
        },
        "responses": { "200": { "description": "Acknowledge with HTTP 200." } }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": ["id", "name", "status"],
        "properties": {
          "id": { "type": "string", "example": "prd_9f2c4a1e" },
          "name": { "type": "string", "example": "Merino Hoodie" },
          "status": { "type": "string", "enum": ["active", "draft", "archived"], "example": "active" },
          "categoryId": { "type": "string", "example": "cat_31a78c47" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }
        }
      },
      "Variant": {
        "type": "object",
        "required": ["id", "sku", "price"],
        "properties": {
          "id": { "type": "string", "example": "var_5b7e2d90" },
          "sku": { "type": "string", "example": "HOODIE-M-NAVY" },
          "options": {
            "type": "object",
            "description": "Variant options like size and color.",
            "example": { "size": "M", "color": "navy" }
          },
          "price": { "$ref": "#/components/schemas/Money" },
          "stock": { "type": "integer", "example": 42 }
        }
      },
      "Money": {
        "type": "object",
        "required": ["amount", "currency"],
        "properties": {
          "amount": { "type": "integer", "description": "Amount in cents.", "example": 8900 },
          "currency": { "type": "string", "example": "EUR" }
        }
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Category": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string", "example": "cat_31a78c47" },
          "name": { "type": "string", "example": "Hoodies & Sweaters" },
          "parentId": { "type": "string", "nullable": true, "example": null }
        }
      },
      "CategoryList": {
        "type": "object",
        "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } }
      },
      "Cart": {
        "type": "object",
        "required": ["id", "items", "totals"],
        "properties": {
          "id": { "type": "string", "example": "crt_c2f063aa" },
          "customerId": { "type": "string", "nullable": true, "example": "cus_74720b46" },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } },
          "totals": {
            "type": "object",
            "properties": {
              "subtotal": { "$ref": "#/components/schemas/Money" },
              "shipping": { "$ref": "#/components/schemas/Money" },
              "tax": { "$ref": "#/components/schemas/Money" },
              "grandTotal": { "$ref": "#/components/schemas/Money" }
            }
          }
        }
      },
      "CartItem": {
        "type": "object",
        "required": ["id", "variantId", "quantity"],
        "properties": {
          "id": { "type": "string", "example": "itm_8d3f1b22" },
          "variantId": { "type": "string", "example": "var_5b7e2d90" },
          "productName": { "type": "string", "example": "Merino Hoodie" },
          "quantity": { "type": "integer", "example": 2 },
          "unitPrice": { "$ref": "#/components/schemas/Money" },
          "lineTotal": { "$ref": "#/components/schemas/Money" }
        }
      },
      "CreateCartRequest": {
        "type": "object",
        "properties": {
          "customerId": { "type": "string", "nullable": true, "example": "cus_74720b46" },
          "currency": { "type": "string", "example": "EUR" }
        }
      },
      "AddCartItemRequest": {
        "type": "object",
        "required": ["variantId", "quantity"],
        "properties": {
          "variantId": { "type": "string", "example": "var_5b7e2d90" },
          "quantity": { "type": "integer", "example": 1 }
        }
      },
      "UpdateCartItemRequest": {
        "type": "object",
        "required": ["quantity"],
        "properties": {
          "quantity": { "type": "integer", "description": "New quantity. `0` removes the item.", "example": 3 }
        }
      },
      "Order": {
        "type": "object",
        "required": ["id", "status", "items", "totals"],
        "properties": {
          "id": { "type": "string", "example": "ord_ad06ea3c" },
          "status": { "type": "string", "enum": ["pending", "paid", "shipped", "refunded", "cancelled"], "example": "paid" },
          "customer": { "$ref": "#/components/schemas/Customer" },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } },
          "totals": {
            "type": "object",
            "properties": {
              "subtotal": { "$ref": "#/components/schemas/Money" },
              "grandTotal": { "$ref": "#/components/schemas/Money" }
            }
          },
          "placedAt": { "type": "string", "format": "date-time", "example": "2026-08-01T14:22:00+00:00" }
        }
      },
      "Customer": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "id": { "type": "string", "example": "cus_74720b46" },
          "email": { "type": "string", "example": "lisa@example.com" },
          "shippingAddress": { "$ref": "#/components/schemas/Address" }
        }
      },
      "Address": {
        "type": "object",
        "required": ["line1", "city", "postalCode", "country"],
        "properties": {
          "line1": { "type": "string", "example": "Speicherstadt 12" },
          "line2": { "type": "string", "nullable": true },
          "city": { "type": "string", "example": "Hamburg" },
          "postalCode": { "type": "string", "example": "20457" },
          "country": { "type": "string", "example": "DE" }
        }
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["cartId", "customer"],
        "properties": {
          "cartId": { "type": "string", "example": "crt_c2f063aa" },
          "customer": { "$ref": "#/components/schemas/Customer" },
          "note": { "type": "string", "nullable": true, "example": "Please gift-wrap." }
        }
      },
      "OrderList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Payment": {
        "type": "object",
        "required": ["id", "status", "amount"],
        "properties": {
          "id": { "type": "string", "example": "pay_66b1e0d4" },
          "status": { "type": "string", "enum": ["captured", "refunded", "failed"], "example": "captured" },
          "method": { "type": "string", "enum": ["card", "paypal", "invoice"], "example": "card" },
          "amount": { "$ref": "#/components/schemas/Money" }
        }
      },
      "CapturePaymentRequest": {
        "type": "object",
        "required": ["method"],
        "properties": {
          "method": { "type": "string", "enum": ["card", "paypal", "invoice"], "example": "card" },
          "token": { "type": "string", "description": "Payment token from the client SDK.", "example": "tok_visa_4242" }
        }
      },
      "RefundRequest": {
        "type": "object",
        "properties": {
          "amount": { "$ref": "#/components/schemas/Money" },
          "reason": { "type": "string", "nullable": true, "example": "Customer returned item." }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "example": 42 },
          "limit": { "type": "integer", "example": 25 },
          "offset": { "type": "integer", "example": 0 }
        }
      },
      "Error": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": { "type": "string", "example": "The given data was invalid." },
          "errors": {
            "type": "object",
            "description": "Field specific validation messages.",
            "example": { "variantId": ["The selected variant is out of stock."] }
          }
        }
      },
      "OrderPaidEvent": {
        "type": "object",
        "required": ["id", "event", "dispatchedAt", "body"],
        "properties": {
          "id": { "type": "string", "description": "The webhook id", "example": "0bcbeac6-99e5-4eae-b02d-9e853337bc10" },
          "event": { "type": "string", "enum": ["Order.Paid"], "example": "Order.Paid" },
          "dispatchedAt": { "type": "string", "format": "date-time" },
          "body": { "$ref": "#/components/schemas/Order" }
        }
      },
      "OrderShippedEvent": {
        "type": "object",
        "required": ["id", "event", "dispatchedAt", "body"],
        "properties": {
          "id": { "type": "string", "example": "8fcbeac6-99e5-4eae-b02d-9e853337bc11" },
          "event": { "type": "string", "enum": ["Order.Shipped"] },
          "dispatchedAt": { "type": "string", "format": "date-time" },
          "body": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string", "example": "ord_ad06ea3c" },
              "carrier": { "type": "string", "example": "DHL" },
              "trackingNumber": { "type": "string", "example": "00340434161094015902" }
            }
          }
        }
      },
      "StockLowEvent": {
        "type": "object",
        "required": ["id", "event", "dispatchedAt", "body"],
        "properties": {
          "id": { "type": "string", "example": "7acbeac6-99e5-4eae-b02d-9e853337bc12" },
          "event": { "type": "string", "enum": ["Inventory.StockLow"] },
          "dispatchedAt": { "type": "string", "format": "date-time" },
          "body": {
            "type": "object",
            "properties": {
              "variantId": { "type": "string", "example": "var_5b7e2d90" },
              "sku": { "type": "string", "example": "HOODIE-M-NAVY" },
              "stock": { "type": "integer", "example": 3 },
              "threshold": { "type": "integer", "example": 5 }
            }
          }
        }
      }
    }
  }
}