openapi: 3.1.0
info:
  title: SAP Commerce Cloud Commerce Web Services API
  description: >-
    RESTful OCC (Omni Commerce Connect) v2 API for SAP Commerce Cloud,
    providing commerce operations including product catalog browsing, cart
    management, checkout, order management, user account management, and
    store locator functionality. This API supports both B2B and B2C
    commerce scenarios.
  version: '2.0'
  contact:
    name: SAP Support
    url: https://support.sap.com/
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
externalDocs:
  description: SAP Commerce Cloud OCC API Documentation
  url: https://help.sap.com/docs/SAP_COMMERCE/d0224eca81e249cb821f2cdf45a82ace/8c19398686691014a8c0fd6c3e5d44a0.html
servers:
  - url: https://{tenant}.{region}.commercecloud.sap/occ/v2/{baseSiteId}
    description: SAP Commerce Cloud Production
    variables:
      tenant:
        description: Tenant identifier
        default: my-tenant
      region:
        description: Deployment region
        default: us
      baseSiteId:
        description: Base site identifier
        default: electronics
tags:
  - name: Addresses
    description: User address management
  - name: Cart
    description: Shopping cart management
  - name: Catalogs
    description: Catalog and category browsing
  - name: Checkout
    description: Checkout and payment operations
  - name: Consents
    description: User consent management
  - name: Orders
    description: Order management and history
  - name: Products
    description: Product catalog browsing and search
  - name: Promotions
    description: Promotions and vouchers
  - name: Stores
    description: Physical store locator
  - name: Users
    description: User account management
security:
  - oauth2: []
paths:
  /products:
    get:
      operationId: searchProducts
      summary: SAP Commerce Cloud Search products
      description: >-
        Search for products using free-text search, category filtering, and
        faceted navigation. Supports pagination, sorting, and spell checking.
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/currentPage'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Product search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchPage'
        '400':
          description: Bad request
  /products/{productCode}:
    get:
      operationId: getProduct
      summary: SAP Commerce Cloud Get product details
      description: >-
        Retrieve detailed information about a specific product including
        descriptions, images, prices, reviews, and classifications.
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/productCode'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
  /products/{productCode}/reviews:
    get:
      operationId: getProductReviews
      summary: SAP Commerce Cloud Get product reviews
      description: >-
        Retrieve customer reviews for a specific product.
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/productCode'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Product reviews
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewList'
    post:
      operationId: createProductReview
      summary: SAP Commerce Cloud Create a product review
      description: >-
        Submit a new customer review for a product.
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/productCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Review'
      responses:
        '201':
          description: Review created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Review'
        '400':
          description: Invalid review data
        '401':
          description: Unauthorized
  /products/{productCode}/stock:
    get:
      operationId: getProductStock
      summary: SAP Commerce Cloud Get product stock levels
      description: >-
        Retrieve stock level information for a product across stores.
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/productCode'
        - name: location
          in: query
          description: Location for store stock lookup
          schema:
            type: string
      responses:
        '200':
          description: Stock information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreFinderStockSearchPage'
        '404':
          description: Product not found
  /catalogs:
    get:
      operationId: getCatalogs
      summary: SAP Commerce Cloud List catalogs
      description: >-
        Retrieve all product catalogs available for the base site.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of catalogs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogList'
  /catalogs/{catalogId}:
    get:
      operationId: getCatalog
      summary: SAP Commerce Cloud Get catalog details
      description: >-
        Retrieve details of a specific catalog.
      tags:
        - Catalogs
      parameters:
        - name: catalogId
          in: path
          required: true
          description: Catalog identifier
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Catalog details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
        '404':
          description: Catalog not found
  /catalogs/{catalogId}/{catalogVersionId}/categories/{categoryId}:
    get:
      operationId: getCatalogCategory
      summary: SAP Commerce Cloud Get category details
      description: >-
        Retrieve details of a specific category within a catalog version.
      tags:
        - Catalogs
      parameters:
        - name: catalogId
          in: path
          required: true
          description: Catalog identifier
          schema:
            type: string
        - name: catalogVersionId
          in: path
          required: true
          description: Catalog version identifier
          schema:
            type: string
        - name: categoryId
          in: path
          required: true
          description: Category identifier
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Category details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '404':
          description: Category not found
  /users/{userId}/carts:
    get:
      operationId: getUserCarts
      summary: SAP Commerce Cloud List user carts
      description: >-
        Retrieve all shopping carts for a specific user.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of carts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartList'
        '401':
          description: Unauthorized
    post:
      operationId: createCart
      summary: SAP Commerce Cloud Create a new cart
      description: >-
        Create a new shopping cart for the user. Can optionally merge
        an anonymous cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - name: oldCartId
          in: query
          description: Anonymous cart ID to merge
          schema:
            type: string
      responses:
        '201':
          description: Cart created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '401':
          description: Unauthorized
  /users/{userId}/carts/{cartId}:
    get:
      operationId: getCart
      summary: SAP Commerce Cloud Get cart details
      description: >-
        Retrieve details of a specific shopping cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Cart details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '404':
          description: Cart not found
    delete:
      operationId: deleteCart
      summary: SAP Commerce Cloud Delete a cart
      description: >-
        Delete a specific shopping cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
      responses:
        '200':
          description: Cart deleted
        '404':
          description: Cart not found
  /users/{userId}/carts/{cartId}/entries:
    get:
      operationId: getCartEntries
      summary: SAP Commerce Cloud List cart entries
      description: >-
        Retrieve all entries (line items) in a shopping cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Cart entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderEntryList'
    post:
      operationId: addCartEntry
      summary: SAP Commerce Cloud Add entry to cart
      description: >-
        Add a product to the shopping cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEntry'
      responses:
        '200':
          description: Entry added to cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartModification'
        '400':
          description: Invalid entry data
  /users/{userId}/carts/{cartId}/entries/{entryNumber}:
    patch:
      operationId: updateCartEntry
      summary: SAP Commerce Cloud Update cart entry
      description: >-
        Update the quantity of an existing cart entry.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/entryNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEntry'
      responses:
        '200':
          description: Entry updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartModification'
        '400':
          description: Invalid entry data
    delete:
      operationId: removeCartEntry
      summary: SAP Commerce Cloud Remove cart entry
      description: >-
        Remove a specific entry from the shopping cart.
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/entryNumber'
      responses:
        '200':
          description: Entry removed
        '404':
          description: Entry not found
  /users/{userId}/carts/{cartId}/deliveryaddress:
    put:
      operationId: setCartDeliveryAddress
      summary: SAP Commerce Cloud Set delivery address
      description: >-
        Set the delivery address for the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - name: addressId
          in: query
          required: true
          description: Address identifier
          schema:
            type: string
      responses:
        '200':
          description: Delivery address set
        '400':
          description: Invalid address
    delete:
      operationId: removeCartDeliveryAddress
      summary: SAP Commerce Cloud Remove delivery address
      description: >-
        Remove the delivery address from the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
      responses:
        '200':
          description: Delivery address removed
  /users/{userId}/carts/{cartId}/deliverymode:
    get:
      operationId: getCartDeliveryMode
      summary: SAP Commerce Cloud Get delivery mode
      description: >-
        Get the current delivery mode for the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Current delivery mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryMode'
    put:
      operationId: setCartDeliveryMode
      summary: SAP Commerce Cloud Set delivery mode
      description: >-
        Set the delivery mode for the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - name: deliveryModeId
          in: query
          required: true
          description: Delivery mode identifier
          schema:
            type: string
      responses:
        '200':
          description: Delivery mode set
        '400':
          description: Invalid delivery mode
    delete:
      operationId: removeCartDeliveryMode
      summary: SAP Commerce Cloud Remove delivery mode
      description: >-
        Remove the delivery mode from the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
      responses:
        '200':
          description: Delivery mode removed
  /users/{userId}/carts/{cartId}/deliverymodes:
    get:
      operationId: getCartDeliveryModes
      summary: SAP Commerce Cloud List delivery modes
      description: >-
        Retrieve all available delivery modes for the cart.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Available delivery modes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryModeList'
  /users/{userId}/carts/{cartId}/paymentdetails:
    post:
      operationId: createCartPaymentDetails
      summary: SAP Commerce Cloud Create payment details
      description: >-
        Add payment details to the cart for checkout.
      tags:
        - Checkout
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDetails'
      responses:
        '201':
          description: Payment details created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDetails'
        '400':
          description: Invalid payment data
  /users/{userId}/carts/{cartId}/vouchers:
    get:
      operationId: getCartVouchers
      summary: SAP Commerce Cloud List applied vouchers
      description: >-
        Retrieve all vouchers applied to the cart.
      tags:
        - Promotions
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Applied vouchers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherList'
    post:
      operationId: applyCartVoucher
      summary: SAP Commerce Cloud Apply voucher to cart
      description: >-
        Apply a voucher code to the cart.
      tags:
        - Promotions
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - name: voucherId
          in: query
          required: true
          description: Voucher code
          schema:
            type: string
      responses:
        '200':
          description: Voucher applied
        '400':
          description: Invalid voucher code
  /users/{userId}/carts/{cartId}/vouchers/{voucherId}:
    delete:
      operationId: removeCartVoucher
      summary: SAP Commerce Cloud Remove voucher from cart
      description: >-
        Remove a previously applied voucher from the cart.
      tags:
        - Promotions
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/cartId'
        - name: voucherId
          in: path
          required: true
          description: Voucher code
          schema:
            type: string
      responses:
        '200':
          description: Voucher removed
        '404':
          description: Voucher not found on cart
  /users/{userId}/orders:
    get:
      operationId: getUserOrders
      summary: SAP Commerce Cloud List user orders
      description: >-
        Retrieve order history for a specific user with pagination.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/currentPage'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Order history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderHistoryList'
        '401':
          description: Unauthorized
    post:
      operationId: placeOrder
      summary: SAP Commerce Cloud Place an order
      description: >-
        Authorize the cart and place the order. The cart must have a
        delivery address, delivery mode, and payment details set.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/userId'
        - name: cartId
          in: query
          required: true
          description: Cart identifier to convert to order
          schema:
            type: string
        - name: termsChecked
          in: query
          required: true
          description: Whether terms and conditions have been accepted
          schema:
            type: boolean
      responses:
        '201':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Cart not ready for checkout
        '401':
          description: Unauthorized
  /users/{userId}/orders/{orderCode}:
    get:
      operationId: getOrder
      summary: SAP Commerce Cloud Get order details
      description: >-
        Retrieve details of a specific order.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/userId'
        - name: orderCode
          in: path
          required: true
          description: Order code
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
  /users/{userId}:
    get:
      operationId: getUser
      summary: SAP Commerce Cloud Get user profile
      description: >-
        Retrieve the profile of a specific user. Use 'current' as userId
        for the currently authenticated user, or 'anonymous' for guest users.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: SAP Commerce Cloud Update user profile
      description: >-
        Update the profile of a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User updated
        '400':
          description: Invalid user data
    delete:
      operationId: deleteUser
      summary: SAP Commerce Cloud Delete user account
      description: >-
        Delete or deactivate a user account.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: User deleted
        '401':
          description: Unauthorized
  /users:
    post:
      operationId: registerUser
      summary: SAP Commerce Cloud Register a new user
      description: >-
        Register a new customer account.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
      responses:
        '201':
          description: User registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid registration data
  /users/{userId}/addresses:
    get:
      operationId: getUserAddresses
      summary: SAP Commerce Cloud List user addresses
      description: >-
        Retrieve all addresses for a specific user.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: User addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressList'
    post:
      operationId: createUserAddress
      summary: SAP Commerce Cloud Create a user address
      description: >-
        Add a new address to the user's address book.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: Address created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Invalid address data
  /users/{userId}/addresses/{addressId}:
    get:
      operationId: getUserAddress
      summary: SAP Commerce Cloud Get user address
      description: >-
        Retrieve a specific address from the user's address book.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/addressId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Address details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '404':
          description: Address not found
    patch:
      operationId: updateUserAddress
      summary: SAP Commerce Cloud Update user address
      description: >-
        Update a specific address in the user's address book.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/addressId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: Address updated
        '400':
          description: Invalid address data
    delete:
      operationId: deleteUserAddress
      summary: SAP Commerce Cloud Delete user address
      description: >-
        Remove an address from the user's address book.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/addressId'
      responses:
        '200':
          description: Address deleted
        '404':
          description: Address not found
  /users/{userId}/paymentdetails:
    get:
      operationId: getUserPaymentDetails
      summary: SAP Commerce Cloud List user payment details
      description: >-
        Retrieve all saved payment details for a user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Payment details list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDetailsList'
  /users/{userId}/consenttemplates:
    get:
      operationId: getConsentTemplates
      summary: SAP Commerce Cloud List consent templates
      description: >-
        Retrieve all consent templates available for the user.
      tags:
        - Consents
      parameters:
        - $ref: '#/components/parameters/userId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Consent templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplateList'
  /users/{userId}/consents:
    post:
      operationId: giveConsent
      summary: SAP Commerce Cloud Give consent
      description: >-
        Give consent for a specific consent template.
      tags:
        - Consents
      parameters:
        - $ref: '#/components/parameters/userId'
        - name: consentTemplateId
          in: query
          required: true
          description: Consent template identifier
          schema:
            type: string
        - name: consentTemplateVersion
          in: query
          required: true
          description: Consent template version
          schema:
            type: integer
      responses:
        '201':
          description: Consent given
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentTemplate'
        '400':
          description: Invalid consent request
  /stores:
    get:
      operationId: searchStores
      summary: SAP Commerce Cloud Search stores
      description: >-
        Search for physical stores by location, coordinates, or query string.
      tags:
        - Stores
      parameters:
        - name: query
          in: query
          description: Free-text search query
          schema:
            type: string
        - name: latitude
          in: query
          description: Latitude for location-based search
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          description: Longitude for location-based search
          schema:
            type: number
            format: double
        - name: radius
          in: query
          description: Search radius in meters
          schema:
            type: number
            format: double
        - $ref: '#/components/parameters/currentPage'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Store search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreFinderSearchPage'
  /stores/{storeId}:
    get:
      operationId: getStore
      summary: SAP Commerce Cloud Get store details
      description: >-
        Retrieve details of a specific physical store.
      tags:
        - Stores
      parameters:
        - name: storeId
          in: path
          required: true
          description: Store identifier
          schema:
            type: string
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Store details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PointOfService'
        '404':
          description: Store not found
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Commerce Cloud
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            basic: Basic access
        password:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            basic: Basic access
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: >-
        User identifier. Use 'current' for the authenticated user
        or 'anonymous' for guest users.
      schema:
        type: string
    cartId:
      name: cartId
      in: path
      required: true
      description: Cart identifier
      schema:
        type: string
    productCode:
      name: productCode
      in: path
      required: true
      description: Product code
      schema:
        type: string
    entryNumber:
      name: entryNumber
      in: path
      required: true
      description: Cart entry number (zero-based index)
      schema:
        type: integer
    addressId:
      name: addressId
      in: path
      required: true
      description: Address identifier
      schema:
        type: string
    query:
      name: query
      in: query
      description: Free-text search query
      schema:
        type: string
    currentPage:
      name: currentPage
      in: query
      description: Current page number (zero-based)
      schema:
        type: integer
        default: 0
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page
      schema:
        type: integer
        default: 20
    sort:
      name: sort
      in: query
      description: Sort criteria (e.g., relevance, topRated, name-asc, price-asc)
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: >-
        Response field configuration level. Use BASIC, DEFAULT, or FULL
        to control the amount of data returned.
      schema:
        type: string
        enum:
          - BASIC
          - DEFAULT
          - FULL
        default: DEFAULT
  schemas:
    Product:
      type: object
      properties:
        code:
          type: string
          description: Product code
        name:
          type: string
          description: Product name
        description:
          type: string
          description: Product description
        summary:
          type: string
          description: Short product summary
        price:
          $ref: '#/components/schemas/Price'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: Product images
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: Product categories
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
          description: Customer reviews
        averageRating:
          type: number
          format: double
          description: Average customer rating
        stock:
          $ref: '#/components/schemas/Stock'
        classifications:
          type: array
          items:
            $ref: '#/components/schemas/Classification'
          description: Product classification attributes
        purchasable:
          type: boolean
          description: Whether the product can be purchased
        url:
          type: string
          description: Product URL
    ProductSearchPage:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          $ref: '#/components/schemas/Pagination'
        sorts:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
        freeTextSearch:
          type: string
          description: Search query that was executed
        currentQuery:
          type: object
          properties:
            query:
              type: object
              properties:
                value:
                  type: string
            url:
              type: string
        facets:
          type: array
          items:
            $ref: '#/components/schemas/Facet'
          description: Search facets for filtering
        breadcrumbs:
          type: array
          items:
            $ref: '#/components/schemas/Breadcrumb'
    Price:
      type: object
      properties:
        currencyIso:
          type: string
          description: ISO 4217 currency code
        value:
          type: number
          format: double
          description: Price value
        formattedValue:
          type: string
          description: Formatted price string
        priceType:
          type: string
          enum:
            - BUY
            - FROM
          description: Price type
    Stock:
      type: object
      properties:
        stockLevelStatus:
          type: string
          enum:
            - inStock
            - lowStock
            - outOfStock
          description: Stock level status
        stockLevel:
          type: integer
          description: Actual stock level quantity
    Image:
      type: object
      properties:
        url:
          type: string
          description: Image URL
        altText:
          type: string
          description: Alternative text
        format:
          type: string
          description: Image format (e.g., thumbnail, product, zoom)
        imageType:
          type: string
          enum:
            - PRIMARY
            - GALLERY
          description: Image type
    Category:
      type: object
      properties:
        code:
          type: string
          description: Category code
        name:
          type: string
          description: Category name
        url:
          type: string
          description: Category URL
        image:
          $ref: '#/components/schemas/Image'
        subcategories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    Catalog:
      type: object
      properties:
        id:
          type: string
          description: Catalog identifier
        name:
          type: string
          description: Catalog name
        catalogVersions:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVersion'
    CatalogVersion:
      type: object
      properties:
        id:
          type: string
          description: Catalog version identifier
        url:
          type: string
          description: Catalog version URL
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    CatalogList:
      type: object
      properties:
        catalogs:
          type: array
          items:
            $ref: '#/components/schemas/Catalog'
    Cart:
      type: object
      properties:
        code:
          type: string
          description: Cart code
        guid:
          type: string
          description: Cart GUID for anonymous carts
        totalPrice:
          $ref: '#/components/schemas/Price'
        totalPriceWithTax:
          $ref: '#/components/schemas/Price'
        subTotal:
          $ref: '#/components/schemas/Price'
        deliveryCost:
          $ref: '#/components/schemas/Price'
        totalTax:
          $ref: '#/components/schemas/Price'
        totalItems:
          type: integer
          description: Total number of items in the cart
        totalUnitCount:
          type: integer
          description: Total unit count across all entries
        entries:
          type: array
          items:
            $ref: '#/components/schemas/OrderEntry'
        deliveryAddress:
          $ref: '#/components/schemas/Address'
        deliveryMode:
          $ref: '#/components/schemas/DeliveryMode'
        paymentInfo:
          $ref: '#/components/schemas/PaymentDetails'
        appliedVouchers:
          type: array
          items:
            $ref: '#/components/schemas/Voucher'
        appliedOrderPromotions:
          type: array
          items:
            $ref: '#/components/schemas/Promotion'
        appliedProductPromotions:
          type: array
          items:
            $ref: '#/components/schemas/Promotion'
        user:
          $ref: '#/components/schemas/Principal'
    CartList:
      type: object
      properties:
        carts:
          type: array
          items:
            $ref: '#/components/schemas/Cart'
    CartModification:
      type: object
      properties:
        statusCode:
          type: string
          description: Status of the modification
        quantity:
          type: integer
          description: Quantity added
        quantityAdded:
          type: integer
          description: Actual quantity added
        entry:
          $ref: '#/components/schemas/OrderEntry'
        statusMessage:
          type: string
          description: Status message
    OrderEntry:
      type: object
      properties:
        entryNumber:
          type: integer
          description: Entry number (zero-based)
        product:
          $ref: '#/components/schemas/Product'
        quantity:
          type: integer
          description: Quantity
        basePrice:
          $ref: '#/components/schemas/Price'
        totalPrice:
          $ref: '#/components/schemas/Price'
        updateable:
          type: boolean
          description: Whether the entry can be updated
    OrderEntryList:
      type: object
      properties:
        orderEntries:
          type: array
          items:
            $ref: '#/components/schemas/OrderEntry'
    Order:
      type: object
      properties:
        code:
          type: string
          description: Order code
        status:
          type: string
          description: Order status
        statusDisplay:
          type: string
          description: Display-friendly order status
        created:
          type: string
          format: date-time
          description: Order creation timestamp
        totalPrice:
          $ref: '#/components/schemas/Price'
        totalPriceWithTax:
          $ref: '#/components/schemas/Price'
        subTotal:
          $ref: '#/components/schemas/Price'
        deliveryCost:
          $ref: '#/components/schemas/Price'
        totalTax:
          $ref: '#/components/schemas/Price'
        totalItems:
          type: integer
          description: Total number of items
        entries:
          type: array
          items:
            $ref: '#/components/schemas/OrderEntry'
        deliveryAddress:
          $ref: '#/components/schemas/Address'
        deliveryMode:
          $ref: '#/components/schemas/DeliveryMode'
        paymentInfo:
          $ref: '#/components/schemas/PaymentDetails'
        consignments:
          type: array
          items:
            $ref: '#/components/schemas/Consignment'
        user:
          $ref: '#/components/schemas/Principal'
    OrderHistoryList:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        pagination:
          $ref: '#/components/schemas/Pagination'
        sorts:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
    Consignment:
      type: object
      properties:
        code:
          type: string
          description: Consignment code
        status:
          type: string
          description: Consignment status
        statusDisplay:
          type: string
          description: Display-friendly status
        trackingID:
          type: string
          description: Shipment tracking ID
        entries:
          type: array
          items:
            $ref: '#/components/schemas/ConsignmentEntry'
        deliveryPointOfService:
          $ref: '#/components/schemas/PointOfService'
    ConsignmentEntry:
      type: object
      properties:
        orderEntry:
          $ref: '#/components/schemas/OrderEntry'
        quantity:
          type: integer
          description: Shipped quantity
        shippedQuantity:
          type: integer
          description: Actual shipped quantity
    User:
      type: object
      properties:
        uid:
          type: string
          description: User unique identifier (email)
        name:
          type: string
          description: Full name
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        titleCode:
          type: string
          description: Title code (mr, mrs, ms, etc.)
        currency:
          $ref: '#/components/schemas/Currency'
        language:
          $ref: '#/components/schemas/Language'
        defaultAddress:
          $ref: '#/components/schemas/Address'
        displayUid:
          type: string
          description: Display UID
    UserRegistration:
      type: object
      required:
        - uid
        - firstName
        - lastName
        - password
      properties:
        uid:
          type: string
          description: Email address as user ID
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        password:
          type: string
          format: password
          description: Account password
        titleCode:
          type: string
          description: Title code
    Address:
      type: object
      properties:
        id:
          type: string
          description: Address identifier
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        titleCode:
          type: string
          description: Title code
        line1:
          type: string
          description: Address line 1
        line2:
          type: string
          description: Address line 2
        town:
          type: string
          description: City or town
        region:
          $ref: '#/components/schemas/Region'
        district:
          type: string
          description: District
        postalCode:
          type: string
          description: Postal or ZIP code
        country:
          $ref: '#/components/schemas/Country'
        phone:
          type: string
          description: Phone number
        email:
          type: string
          description: Email address
        defaultAddress:
          type: boolean
          description: Whether this is the default address
    AddressList:
      type: object
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    Country:
      type: object
      properties:
        isocode:
          type: string
          description: ISO 3166-1 alpha-2 country code
        name:
          type: string
          description: Country name
    Region:
      type: object
      properties:
        isocode:
          type: string
          description: Region ISO code
        name:
          type: string
          description: Region name
    Currency:
      type: object
      properties:
        isocode:
          type: string
          description: ISO 4217 currency code
        name:
          type: string
          description: Currency name
        symbol:
          type: string
          description: Currency symbol
    Language:
      type: object
      properties:
        isocode:
          type: string
          description: ISO 639-1 language code
        name:
          type: string
          description: Language name
    DeliveryMode:
      type: object
      properties:
        code:
          type: string
          description: Delivery mode code
        name:
          type: string
          description: Delivery mode name
        description:
          type: string
          description: Delivery mode description
        deliveryCost:
          $ref: '#/components/schemas/Price'
    DeliveryModeList:
      type: object
      properties:
        deliveryModes:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryMode'
    PaymentDetails:
      type: object
      properties:
        id:
          type: string
          description: Payment details identifier
        accountHolderName:
          type: string
          description: Card holder name
        cardNumber:
          type: string
          description: Masked card number
        cardType:
          type: object
          properties:
            code:
              type: string
              description: Card type code
            name:
              type: string
              description: Card type name
        expiryMonth:
          type: string
          description: Card expiry month
        expiryYear:
          type: string
          description: Card expiry year
        billingAddress:
          $ref: '#/components/schemas/Address'
        defaultPayment:
          type: boolean
          description: Whether this is the default payment method
        saved:
          type: boolean
          description: Whether the payment details are saved
    PaymentDetailsList:
      type: object
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentDetails'
    Voucher:
      type: object
      properties:
        code:
          type: string
          description: Voucher code
        name:
          type: string
          description: Voucher name
        description:
          type: string
          description: Voucher description
        value:
          type: number
          format: double
          description: Voucher value
        valueFormatted:
          type: string
          description: Formatted voucher value
        voucherCode:
          type: string
          description: Applied voucher code
        freeShipping:
          type: boolean
          description: Whether voucher provides free shipping
    VoucherList:
      type: object
      properties:
        vouchers:
          type: array
          items:
            $ref: '#/components/schemas/Voucher'
    Promotion:
      type: object
      properties:
        code:
          type: string
          description: Promotion code
        title:
          type: string
          description: Promotion title
        description:
          type: string
          description: Promotion description
        promotionType:
          type: string
          description: Promotion type
    ConsentTemplate:
      type: object
      properties:
        id:
          type: string
          description: Consent template identifier
        name:
          type: string
          description: Template name
        description:
          type: string
          description: Template description
        version:
          type: integer
          description: Template version
        currentConsent:
          type: object
          properties:
            consentGivenDate:
              type: string
              format: date-time
            consentWithdrawnDate:
              type: string
              format: date-time
    ConsentTemplateList:
      type: object
      properties:
        consentTemplates:
          type: array
          items:
            $ref: '#/components/schemas/ConsentTemplate'
    PointOfService:
      type: object
      properties:
        name:
          type: string
          description: Store name
        displayName:
          type: string
          description: Display name
        description:
          type: string
          description: Store description
        address:
          $ref: '#/components/schemas/Address'
        geoPoint:
          $ref: '#/components/schemas/GeoPoint'
        openingHours:
          $ref: '#/components/schemas/OpeningSchedule'
        storeImages:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        features:
          type: object
          additionalProperties:
            type: string
          description: Store features
    GeoPoint:
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: Latitude
        longitude:
          type: number
          format: double
          description: Longitude
    OpeningSchedule:
      type: object
      properties:
        weekDayOpeningList:
          type: array
          items:
            type: object
            properties:
              weekDay:
                type: string
              openingTime:
                type: object
                properties:
                  formattedHour:
                    type: string
              closingTime:
                type: object
                properties:
                  formattedHour:
                    type: string
              closed:
                type: boolean
    StoreFinderSearchPage:
      type: object
      properties:
        stores:
          type: array
          items:
            $ref: '#/components/schemas/PointOfService'
        pagination:
          $ref: '#/components/schemas/Pagination'
        sorts:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
    StoreFinderStockSearchPage:
      type: object
      properties:
        stores:
          type: array
          items:
            type: object
            properties:
              pointOfService:
                $ref: '#/components/schemas/PointOfService'
              stockInfo:
                $ref: '#/components/schemas/Stock'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Classification:
      type: object
      properties:
        code:
          type: string
          description: Classification code
        name:
          type: string
          description: Classification name
        features:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              name:
                type: string
              featureValues:
                type: array
                items:
                  type: object
                  properties:
                    value:
                      type: string
    Review:
      type: object
      properties:
        id:
          type: string
          description: Review identifier
        headline:
          type: string
          description: Review headline
        comment:
          type: string
          description: Review text
        rating:
          type: number
          format: double
          description: Rating value
        date:
          type: string
          format: date-time
          description: Review date
        alias:
          type: string
          description: Reviewer alias
        principal:
          $ref: '#/components/schemas/Principal'
    ReviewList:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
    Principal:
      type: object
      properties:
        uid:
          type: string
          description: User unique identifier
        name:
          type: string
          description: Display name
    Facet:
      type: object
      properties:
        name:
          type: string
          description: Facet name
        priority:
          type: integer
          description: Display priority
        category:
          type: boolean
          description: Whether this is a category facet
        multiSelect:
          type: boolean
          description: Whether multiple values can be selected
        visible:
          type: boolean
          description: Whether the facet is visible
        values:
          type: array
          items:
            $ref: '#/components/schemas/FacetValue'
    FacetValue:
      type: object
      properties:
        name:
          type: string
          description: Facet value name
        count:
          type: integer
          description: Number of results
        selected:
          type: boolean
          description: Whether this value is selected
        query:
          type: object
          properties:
            query:
              type: object
              properties:
                value:
                  type: string
            url:
              type: string
    Breadcrumb:
      type: object
      properties:
        facetCode:
          type: string
        facetName:
          type: string
        facetValueCode:
          type: string
        facetValueName:
          type: string
        removeQuery:
          type: object
          properties:
            query:
              type: object
              properties:
                value:
                  type: string
            url:
              type: string
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of results per page
        totalPages:
          type: integer
          description: Total number of pages
        totalResults:
          type: integer
          description: Total number of results
    Sort:
      type: object
      properties:
        code:
          type: string
          description: Sort code
        name:
          type: string
          description: Sort display name
        selected:
          type: boolean
          description: Whether this sort is selected