openapi: 3.1.0
info:
  title: Shopware Store API
  version: 6.7.9999999-dev
  description: >-
    The Shopware Store API is the customer-facing API for building headless
    storefronts and progressive web apps. It exposes 78 endpoints covering
    product catalog browsing, cart management, checkout, customer authentication,
    and order history. Catalog endpoints are public; customer-specific operations
    require a context token in the sw-context-token header.
  contact:
    name: Shopware Developer Documentation
    url: https://developer.shopware.com/docs/concepts/api/store-api.html
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
externalDocs:
  description: Full interactive specification (Stoplight)
  url: https://shopware.stoplight.io/docs/store-api
servers:
  - url: https://{shopDomain}/store-api
    description: Shopware Store API endpoint
    variables:
      shopDomain:
        default: your-shop.example.com
        description: Hostname of the Shopware instance
security:
  - swAccessKey: []
paths:
  /product:
    get:
      operationId: listStoreProducts
      summary: List products
      description: Returns a paginated list of publicly visible products.
      tags:
        - Product
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Paginated product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
  /product/{productId}:
    get:
      operationId: getStoreProduct
      summary: Get a product
      description: Returns a single product by ID including all variants and media.
      tags:
        - Product
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: Product detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetailResponse'
        '404':
          description: Product not found
  /search:
    post:
      operationId: searchStore
      summary: Search products
      description: >-
        Search for products in the storefront. Supports filters, sorting,
        aggregations and full-text search.
      tags:
        - Search
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCriteria'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
  /checkout/cart:
    get:
      operationId: getCart
      summary: Fetch or create a cart
      description: >-
        Returns the current active cart for the customer session. Creates a new
        cart if none exists.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: Current cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    delete:
      operationId: deleteCart
      summary: Delete a cart
      description: Removes the current cart for the customer session.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '204':
          description: Cart deleted
  /checkout/cart/line-item:
    post:
      operationId: addLineItems
      summary: Add items to the cart
      description: Adds one or more line items (products, promotions) to the cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItems'
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    patch:
      operationId: updateLineItems
      summary: Update items in the cart
      description: Updates quantities or properties of existing line items.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItemsUpdate'
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    delete:
      operationId: removeLineItems
      summary: Remove items from the cart
      description: Removes one or more line items by their IDs.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
        - name: ids
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /checkout/order:
    post:
      operationId: createOrder
      summary: Create order from cart
      description: Converts the current cart into an order.
      tags:
        - Checkout
        - Order
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Validation error (e.g. insufficient stock)
  /account/login:
    post:
      operationId: loginCustomer
      summary: Log in a customer
      description: Authenticates a customer and returns an updated context token.
      tags:
        - Account
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Login successful; new context token returned in header
          headers:
            sw-context-token:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  contextToken:
                    type: string
        '401':
          description: Invalid credentials
  /account/logout:
    post:
      operationId: logoutCustomer
      summary: Log out a customer
      description: Ends the customer session and invalidates the context token.
      tags:
        - Account
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: Logout successful
  /account/register:
    post:
      operationId: registerCustomer
      summary: Register a customer
      description: Creates a new customer account.
      tags:
        - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRegistration'
      responses:
        '200':
          description: Registration successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /account/order:
    get:
      operationId: listCustomerOrders
      summary: List customer orders
      description: Returns order history for the currently authenticated customer.
      tags:
        - Account
        - Order
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /navigation/{activeId}/{rootId}:
    post:
      operationId: getNavigation
      summary: Fetch navigation menu
      description: Returns a navigation category tree starting from a given root.
      tags:
        - Navigation
      parameters:
        - name: activeId
          in: path
          required: true
          schema:
            type: string
          description: ID of the currently active navigation node
        - name: rootId
          in: path
          required: true
          schema:
            type: string
          description: ID of the root navigation node
        - $ref: '#/components/parameters/SwContextToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCriteria'
      responses:
        '200':
          description: Navigation tree
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationCategory'
  /category:
    get:
      operationId: listStoreCategories
      summary: List categories
      description: Returns all product categories visible in the storefront.
      tags:
        - Category
      parameters:
        - $ref: '#/components/parameters/SwContextToken'
      responses:
        '200':
          description: Category list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListResponse'
components:
  securitySchemes:
    swAccessKey:
      type: apiKey
      in: header
      name: sw-access-key
      description: Sales channel access key
  parameters:
    SwContextToken:
      name: sw-context-token
      in: header
      description: Customer session context token
      schema:
        type: string
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 25
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
  schemas:
    Cart:
      type: object
      description: Shopware shopping cart
      properties:
        name:
          type: string
          description: Cart name (e.g. guest-cart)
        token:
          type: string
          description: Context token identifying the cart and user session
        price:
          $ref: '#/components/schemas/CalculatedPrice'
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
          description: All items within the cart
        errors:
          type: object
          description: Cart errors (insufficient stock, invalid addresses, invalid vouchers)
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/CartDelivery'
        transactions:
          type: array
          items:
            type: object
            properties:
              paymentMethodId:
                type: string
              amount:
                $ref: '#/components/schemas/CalculatedPrice'
        modified:
          type: boolean
          description: Indicates any changes to the cart
        customerComment:
          oneOf:
            - type: string
            - type: 'null'
        affiliateCode:
          oneOf:
            - type: string
            - type: 'null'
    LineItem:
      type: object
      description: A line item within a cart
      properties:
        id:
          type: string
        referencedId:
          type: string
          description: ID of the referenced product or promotion
        label:
          type: string
        quantity:
          type: integer
        type:
          type: string
          enum:
            - product
            - promotion
            - credit
            - custom
        price:
          $ref: '#/components/schemas/CalculatedPrice'
        good:
          type: boolean
        removable:
          type: boolean
        stackable:
          type: boolean
        modified:
          type: boolean
    CartItems:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - id
              - referencedId
              - type
              - quantity
            properties:
              id:
                type: string
              referencedId:
                type: string
              type:
                type: string
                enum:
                  - product
                  - promotion
              quantity:
                type: integer
                minimum: 1
    CartItemsUpdate:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - id
              - quantity
            properties:
              id:
                type: string
              quantity:
                type: integer
                minimum: 1
    CalculatedPrice:
      type: object
      properties:
        unitPrice:
          type: number
          format: float
        totalPrice:
          type: number
          format: float
        quantity:
          type: integer
        calculatedTaxes:
          type: array
          items:
            type: object
            properties:
              tax:
                type: number
              taxRate:
                type: number
              price:
                type: number
        taxRules:
          type: array
          items:
            type: object
    CartDelivery:
      type: object
      properties:
        trackingCodes:
          type: array
          items:
            type: string
        location:
          type: object
        deliveryDate:
          type: object
        shippingMethod:
          type: object
        shippingOrderAddress:
          type: object
        positions:
          type: array
          items:
            type: object
    Order:
      type: object
      properties:
        id:
          type: string
        orderNumber:
          type: string
        orderDateTime:
          type: string
          format: date-time
        amountTotal:
          type: number
          format: float
        amountNet:
          type: number
          format: float
        lineItems:
          type: array
          items:
            type: object
        stateMachineState:
          type: object
          properties:
            name:
              type: string
            technicalName:
              type: string
        billingAddress:
          type: object
    OrderListResponse:
      type: object
      properties:
        total:
          type: integer
        elements:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    Product:
      type: object
      properties:
        id:
          type: string
        productNumber:
          type: string
        name:
          type: string
        description:
          type: string
        active:
          type: boolean
        cover:
          type: object
          properties:
            id:
              type: string
            url:
              type: string
        calculatedPrice:
          $ref: '#/components/schemas/CalculatedPrice'
        calculatedListingPrice:
          type: object
        availableStock:
          type: integer
    ProductListResponse:
      type: object
      properties:
        total:
          type: integer
        elements:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    ProductDetailResponse:
      type: object
      properties:
        product:
          $ref: '#/components/schemas/Product'
        configurator:
          type: array
          items:
            type: object
    Customer:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        customerNumber:
          type: string
    CustomerRegistration:
      type: object
      required:
        - email
        - password
        - firstName
        - lastName
        - salutationId
        - billingAddress
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        firstName:
          type: string
        lastName:
          type: string
        salutationId:
          type: string
        billingAddress:
          type: object
          required:
            - street
            - zipcode
            - city
            - countryId
          properties:
            street:
              type: string
            zipcode:
              type: string
            city:
              type: string
            countryId:
              type: string
    StoreCriteria:
      type: object
      properties:
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 24
        filter:
          type: array
          items:
            type: object
        sort:
          type: array
          items:
            type: object
        term:
          type: string
        includes:
          type: object
    NavigationCategory:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        active:
          type: boolean
        type:
          type: string
        children:
          type: array
          items:
            $ref: '#/components/schemas/NavigationCategory'
    CategoryListResponse:
      type: object
      properties:
        total:
          type: integer
        elements:
          type: array
          items:
            type: object
tags:
  - name: Product
    description: Browse the product catalog
  - name: Cart
    description: Manage the shopping cart and its line items
  - name: Checkout
    description: Complete the purchase workflow
  - name: Order
    description: Access order history and details
  - name: Account
    description: Customer registration, login and profile management
  - name: Navigation
    description: Fetch storefront navigation menus
  - name: Category
    description: Browse product categories
  - name: Search
    description: Full-text and faceted product search