This API is designed for use with headless shop frontends, such as the novomind iSHOP Storefront or SHOPin by Creative Style.

For accessing the relevant version of the documentation, you can also utilize the Apollo Router Studio on your novomind iSHOP installation:

https://<your-url-here>/api/graphql/

This API includes comprehensive management of customer and order data, shopping carts and wishlists, payment and promotion processing, as well as querying product data, category data, and maintained shop parameters. These functions are delivered by various microservices, which are combined into a supergraph. The endpoint for this supergraph is an Apollo Router with gateway functionalities, allowing the creation of a single GraphQL request that utilizes these microservices. The gateway is secured by OAuth 2.0. All requests must be made with a valid JSON Web Token, which must be obtained from an Authentication Service endpoint beforehand.

The API offers extensive capabilities for managing customer and order data, handling shopping carts and wishlists, processing payments and promotions, and querying product and category data, along with other shop parameters. These functionalities are powered by various microservices, which are aggregated into a supergraph. This supergraph is accessible via an Apollo Router with gateway functionality, enabling a unified GraphQL request that interacts with all the microservices. The gateway is secured by OAuth 2.0, requiring all requests to include a valid JSON Web Token (JWT), which must be obtained in advance from an Authentication Service endpoint.

If you intend to implement backend features or extend the APIs please refer to our documentation for novomind iSHOP headless backend development. Please note that this documentation is not publicly available.

Before proceeding, please make sure to review the authentication guide.

For being able to use the API a valid JSON Web Token (JWT) is needed. The Authentication-Service supports client_credentials, authorization_code, and refresh_token as grant types. Which grant types are available for a particular client depends on its configuration. The required JWT needs to be requested from the Authentication-Service endpoint.

Independent on the grant type the process ends with a JSON response that contains the attribute "access_token" with the JWT as value. This JWT has to be used as header parameter for requests to the gateway:

• Header Key: "Authorization"
• Header Value: "Bearer <fetched JWT>"

To get the right credentials for fetching JWTs please ask someone from our team.

Guest Customers

Any interaction with the shop needs at least a guest token. The grant type client_credentials with the clients credentials and a uuid from the user is used to generate the JWT. The uuid from the user is either located in a cookie or it is generated.

The relevant properties are:

• Access Token URL: <auth-service-url>/oauth2/token
• Client ID: <Client ID>
• Client Secret: <matching password for the Client ID>
• Grant Type: Client Credentials
• Scope: shop-guest

After fetching the token it can be tested that everything works with the following query:

query Shop_findCarts {
  shop_findCarts {
    id
  }
}

Since nothing has been done with the customer yet the result should be empty like this response:

{
  "data": {
    "shop_findCarts": []
  }
}

Registering a Customer

The login page on the Authorization-Service contains a register form as well. At least one request of the user on the Authorization-Service must be done with the mcs as a parameter. (e.g. /login/?mcs=%5Bbrand%3Dnovosales%20channel%3Dweb%20country%3Dde%20currency%3DEUR%20language%3Dde%20store%3D%5D) The value is stored in the session and will be used later in the registration process.

<auth-service-url>/login/?mcs=<existing MCS string>

Registered Customers

For registered users the grant type authorization_code is used. The client creates a redirect to the Authorization-Service Auth URL that contains a Callback URL (parameter redirect_uri), the clientId, scope=shop-customer, response_type=code and the mcs. Besides that the target of the user will be remembered by the client. It is possible to use the state parameter to carrier over data, like the target, from the Auth URL to the Callback URL.

The user follows the redirect to the Auth URL:

• If the user is not logged in to the Authorization-Service, the login page will be shown. With username and password the user can login and the Auth URL will be called again.

• If the user is logged in and the Auth URL is called a redirect to the Callback URL that contains a code parameter is returned. The user calls the Callback URL on the client. Afterwards the client uses the Access Token URL with parameters code, which is from the Callback URL, the same redirect_uri as used with the Auth URL and grant_type=authorize_code.

The response is a JSON that contains the access_token and if the client has the right the refresh_token as well. In the default configuration of clients the permissions are implicit, so no additional window will pop up in the authorization process.

The required properties are:

• Auth URL: <auth-service-url>/oauth2/authorize?mcs=<existing MCS string>
• Access Token URL: <auth-service-url>/oauth2/token
• Callback URL: <matching URL with the clients configuration from the Authentication-Service>
• Client ID: <Client ID>
• Client Secret: <matching password for the Client ID>
• Grant Type: Authorization Code
• Scope: shop-customer

After fetching the token it can be tested that everything works with the following query:

query Account_loadCustomer {
  account_loadCustomer {
    firstname
    lastname
  }
}

Assuming for the registration was used John as firstname and Doe as lastname the response should like:

{
  "data": {
    "account_loadCustomer": {
      "firstname": "John",
      "lastname": "Doe"
    }
  }
}

If this query is used with a JWT for a guest customer it would result in an error with message Forbidden.

For clients with the right to use "refresh_token" a new pair of tokens can be created using the Access Token URL with the following parameters only:

• grant_type=refresh_token
• refresh_token=<refresh_token>

Refresh tokens can be reusable or not, depending on the clients configuration. Reusable refresh tokens can be used infinitely in their time-to-live to get new access tokens. Non-reusable refresh tokens can be used once in their time-to-live to generate a new token pair. The new refresh token then has its own time-to-live, which allows to stay logged in forever if refreshed often enough.

This guide demonstrates how to implement modern product listings using the GraphQL API of the novomind iSHOP. Learn to efficiently fetch product data, implement pagination/sorting, optimize for performance, and leverage built-in features like recommendations and SEO.

Basic Product Listing Implementation

query ProductListing($categoryId: ID!, $pageSize: Int = 20, $pageIndex: Int = 0) {
  core_category(id: $categoryId) {
    id
    name
    description
    seoThumbnail
    products(paging: {limit: $pageSize, offset: $pageIndex*$pageSize}) {
      total
      items {
        id
        name
        sku
        price {
          gross
          net
          currency
        }
        availability
        thumbnail
        rating
      }
    }
    topsellers(limit: 5) {
      id
      name
      thumbnail
    }
  }
}

Key Implementation Aspects

Pagination Strategy

• Implement "Load More" pattern using total count and page calculations
• Store current page state: totalPages = Math.ceil(total / pageSize)
• Example pagination controls:

  const handlePageChange = (newPage) => {
    fetchData({
      variables: {
        pageSize: 20,
        pageIndex: newPage
      }
    });
  };
  

Product Card Components

• Display core fields:
  • thumbnail image
  • name + sku
  • Formatted price.gross with currency
  • Stock indicator using availability
  • Rating stars from rating field

SEO meta data

• Use category's built-in SEO data:

  seo {
    title
    description
    keywords
  }
  

• Implement schema.org markup using product data
• Generate canonical URLs based on pagination

Advanced Features

Sorting Implementation

products(
  paging: {limit: 20, offset: 0}
  sorting: {field: PRICE, order: ASC}
) {
  # ... fields ...
}

• Supported sort fields (check schema):
  • NAME
  • PRICE
  • RELEVANCE
  • NEWEST

Filter Integration

products(
  filters: [
    {attribute: "color", values: ["red", "blue"]}
    {priceRange: {min: 50, max: 100}}
  ]
) {
  # ... fields ...
}

• Map UI filters to GraphQL input types
• Handle filter combinations with state management

Performance Optimizations

Image Loading

thumbnail(size: "400x400", format: WEBP)

• Use responsive image techniques:

  images {
    xs: url(size: "200x200")
    sm: url(size: "400x400")
    lg: url(size: "800x800")
  }
  

Caching Strategy

• Use Apollo Cache policies
• Cache partial results for instant navigation
• Implement cache-and-network fetch policy

Caching might be challenging and might lead to potential issues. Please refer to novomind for suggestions on how to implement proper caching mechanisms.

Error States & Edge Cases

• Handle empty states:

  {data?.products?.items?.length === 0 && <EmptyList />}
  

• Manage loading skeletons during fetches
• Handle category redirects:

  core_category(id: $id) {
    redirect {
      target
      code
    }
  }
  

Recommendations Integration

core_categoryRecommendations(categoryId: $id) {
  items {
    id
    name
    thumbnail
  }
}

• Display "Related Categories" section
• Implement carousel component for recommendations

Implementation Checklist

1. Set up Apollo Client with error handling
2. Create pagination component
3. Build product card template
4. Implement sorting/filtering UI
5. Add loading states
6. Configure SEO meta tags
7. Set up analytics tracking
8. Implement mobile-responsive grid

The novomind iSHOP Backoffice is a CMS to create content for exisiting PIM categories, new pages or other areas of your shop.

The first step is to create grids in the Grid Manager, you can use these grids on pages to add content ("teaser") to the grid cells in Categories and Pages or Other Maintenance Levels.

Here's a comprehensive guide to CMS grid and teaser functionality based on typical ecommerce implementations:

---

CMS Grids & Teasers Implementation Guide

1. Core Concepts

Grid System

• Definition: Structural containers that organize content into rows/columns
• Key Features:
  • Responsive column layouts (2-6 columns)
  • Nestable structure (grids within grids)
  • Zone-based positioning (header, footer, product detail areas)
• Schema Reference:

  type GridAttribute implements ContentAttribute {
    name: String!
    columns: Int!
    elements: [ContentAttribute!]! # Can contain teasers or nested grids
  }
  

Teasers

• Definition: Pre-configured content modules with various display formats
• Common Types:
  • Slider Teasers: Image carousels with text overlays
  • Product Teasers: Featured item showcases
  • Text Teasers: Promotional content blocks
  • Brand Teasers: Manufacturer/product line highlights
• Schema Reference:

  type SliderTeaser implements ContentAttribute & TeaserAttribute {
    meta: TeaserMeta!
    tabs: [SliderTeaserTab]!
  }
  

---

2. Implementation Workflow

Step 1: Fetch Grid Layout

query GetPageLayout($pageId: ID!) {
  page(id: $pageId) {
    attributes {
      ... on GridAttribute {
        name
        columns
        elements {
          __typename
          ... on SliderTeaser {
            tabs {
              headline
              image { url altText }
              trackingInfo
            }
          }
          ... on ProductTeaser {
            products {
              id
              name
              price
            }
          }
        }
      }
    }
  }
}

Step 2: Grid Component Implementation (React Example)

const GridRenderer = ({ grid }) => (
  <div className={`grid grid-cols-${grid.columns}`}>
    {grid.elements.map((element, index) => (
      <div key={index} className="grid-item">
        {element.__typename === 'SliderTeaser' && (
          <SliderTeaserComponent data={element} />
        )}
        {element.__typename === 'ProductTeaser' && (
          <ProductTeaserComponent data={element} />
        )}
      </div>
    ))}
  </div>
);

Here's a Vue.js-focused implementation guide with Apollo Client and a 12-column grid system:

<!-- CMSGridRenderer.vue -->
            <template>
              <div class="grid grid-cols-12 gap-4">
                <template v-for="(element, index) in elements" :key="index">
                  <!-- Grid Container -->
                  <div v-if="element.__typename === 'GridAttribute'" 
                       :class="`col-span-${element.columns}`">
                    <CMSGridRenderer :elements="element.elements" />
                  </div>
            
                  <!-- Teaser Components -->
                  <div v-if="element.__typename === 'SliderTeaser'" 
                       :class="`col-span-${element.meta?.width || 12}`">
                    <SliderTeaser :tabs="element.tabs" />
                  </div>
            
                  <div v-if="element.__typename === 'ProductTeaser'"
                       :class="`col-span-${element.meta?.width || 12}`">
                    <ProductTeaser :products="element.products" />
                  </div>
                </template>
              </div>
            </template>
            
            <script setup>
            import { useQuery } from '@vue/apollo-composable'
            import gql from 'graphql-tag'
            
            const props = defineProps({
              elements: {
                type: Array,
                default: () => []
              }
            })
            
            // Apollo Query Example
            const { result, loading, error } = useQuery(gql`
              query GetPageLayout($pageId: ID!) {
                page(id: $pageId) {
                  attributes {
                    __typename
                    ... on GridAttribute {
                      columns
                      elements {
                        __typename
                        ... on SliderTeaser {
                          tabs {
                            headline
                            image { url altText }
                          }
                          meta { width }
                        }
                        ... on ProductTeaser {
                          products {
                            id
                            name
                            price
                          }
                          meta { width }
                        }
                      }
                    }
                  }
                }
              }
            `, {
              pageId: 'homepage' // Dynamic ID from route
            })
            </script>
            

Step 3: Teaser Components

Slider Teaser Implementation:

const SliderTeaserComponent = ({ data }) => (
  <div className="slider-teaser">
    {data.tabs.map((tab, index) => (
      <div key={index} className="slide">
        <img 
          src={tab.image.url} 
          alt={tab.image.altText}
          className="teaser-image"
        />
        <div className="teaser-content">
          <h2>{tab.headline}</h2>
          <p>{tab.subHeadline}</p>
        </div>
      </div>
    ))}
  </div>
);

Product Teaser Implementation:

const ProductTeaserComponent = ({ data }) => (
  <div className="product-teaser">
    <h3>Featured Products</h3>
    <div className="product-grid">
      {data.products.map(product => (
        <ProductCard 
          key={product.id}
          name={product.name}
          price={product.price}
          image={product.images[0]}
        />
      ))}
    </div>
  </div>
);

---

3. Key Features & Best Practices

Responsive Grid Handling

/* Base grid styles */
            .grid {
              display: grid;
              gap: 1.5rem;
              padding: 1rem;
            }
            
            /* Column variations */
            .grid-cols-2 { grid-template-columns: repeat(2, 1fr); }
            .grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
            
            /* Mobile adaptation */
            @media (max-width: 768px) {
              .grid { grid-template-columns: 1fr; }
            }
            

Teaser Configuration Options

Property	Type	Description
columns	int	Grid column count (2-6)
meta.zone	string	Placement area (header/main/footer)
meta.priority	int	Display order in zone
image.size	string	Responsive image breakpoints

Performance Optimization

1. Image Handling:

   image {
     url(size: "800x600", format: WEBP)
     srcSet(sizes: ["400x300", "800x600"])
   }
   

2. Lazy Loading:

   <img loading="lazy" decoding="async" ...>
   

3. Caching Strategy:

   // Apollo Client configuration
   new InMemoryCache({
     typePolicies: {
       GridAttribute: { merge: true }
     }
   })
   

Tracking & Analytics

// Teaser interaction tracking
const handleTeaserClick = (teaserData) => {
  analytics.track('teaser_click', {
    teaser_id: teaserData.meta.id,
    zone: teaserData.meta.zone,
    content_type: teaserData.__typename
  });
};

---

4. Content Relationships

graph TD
    A[Page] --> B[Grid]
    B --> C[Teaser 1]
    B --> D[Teaser 2]
    B --> E[Nested Grid]
    E --> F[Teaser 3]
    E --> G[Teaser 4]

---

5. Troubleshooting Common Issues

Problem: Teasers not appearing in correct grid
Solution

1. Verify zone configuration in CMS
2. Check grid columns vs teaser meta.width
3. Validate cache invalidation strategy

Problem: Image quality issues
Solution

# Use optimized image formats
image {
  url(format: WEBP, quality: 80)
}

Problem: Tracking not working
Solution

1. Check trackingInfo field population
2. Verify analytics implementation
3. Test with preview mode disabled

---

6. Advanced Implementation

Dynamic Grid Layouts

// Dynamic class binding for Tailwind
const GridContainer = ({ columns }) => (
  <div className={`grid grid-cols-${columns} gap-4`}>
    {/* Teaser components */}
  </div>
);

Personalized Content

You can create customer segments in the iSHOP Backoffice based on various parameters. Use these segments to differentiate content between different target audiences:

query GetPersonalizedTeasers($segment: String!) {
  teasers(filter: { audienceSegment: $segment }) {
    # Personalized content
  }
}

The Shop API differentiates between carts and wishlists for all customers.

The Cart contains:

• Positions
• Billing address
• Shipping address
• Selected payment method
• Selected shipping method
• Other properties

For B2C purposes there is only one cart per user. If there is no cart, then one will be created on demand. The most important mutation operation is cart_update. It allows to modify positions, set addresses, payment methods, etc.

The Wishlist contains:

• Positions

Customers can have multiple wishlists that they can organize themselves.

Cart To Wishlist

With the cart_addAllToWishlist mutation it is possible to move all positions from a cart to the wishlist of a customer. The cart is empty afterwards. If the wishlist already contains positions with the same item id, they will be merged into one position.

Wishlist To Cart

With the wishlist_addAllToCartmutation all positions from the wishlist are moved to the cart of the customer. Positions that have no quantity on the wishlist will be moved with quantity set to 1. If the cart already contains positions with the same item id, they will be merged into one position.

The checkout process is done via shop_submitOrder mutation. This page describes the minimum requirements to place an order successfully.

Minimum Requirements

Orders can be submitted for both types of customers if the following minimum requirements are met.

For registered users the guestId may not be set, as it would turn it into a guest order.

Mutation query:

mutation Mutation($data: UpdateCartInput!) {
    cart_update(data: $data) {
        ... on UpdateCartSuccess {
            cart {
                id
            }
        }
    }
}

Variables for the mutation (just for showcasing):

{
  "data": {
    "ops": [
      {
        "setBillingAddress": {
          "value": {
            "salutation": "MR",
            "firstname": "John",
            "lastname": "Doe",
            "street": "Any Street",
            "number": "1",
            "city": "Any City",
            "postcode": "12345",
            "country": "Any Country"
          }
        },
        "setGuestId": {
          "value": "<user identifier e.g. e-mail>"
        },
        "setPaymentMethod": {
          "value": {
            "interfaceId": "<valid interface id>",
            "methodCode": "<valid method code>"
          }
        },
        "setShippingMethod": {
          "value": {
            "shipperId": "<valid shipper id>"
          }
        },
        "positionOp": {
          "addPosition": {
            "setItemId": {
              "value": "<valid item id>"
            },
            "updateQuantity": {
              "quantity": 1
            }
          }
        }
      }
    ]
  }
}

Afterwards the mutation shop_submitOrder can be used to submit the order with the given cartId.

Supporting Operations

To get a list of the available shipping methods the following query can be used:

query Query {
  shop_findCarts {
    availableShippingMethods {
      amount {
        amount
        currencyCode
        currencySymbol
        intAmount
        precision
        stringValue
      }
      description
      freeShipping
      name
      shipperId
    }
  }
}

To get a list of the available payment methods the following query can be used:

query Cart_availablePayments($cartId: ID!) {
  cart_availablePayments(cartId: $cartId) {
    interfaceId
    methodCodes
  }
}
# with variable:
{
  "cartId": "<cart id that will be submitted>"
}

Mutation paypal_createOrder

If an order with payment method PayPal gets submitted the mutation paypal_createOrder with the orderId that is returned by shop_submitOrder is needed to start the PayPal payment process. Afterwards an approval link is returned where the payment gets handled. The customer logs into PayPal, selects the payment options and then returns to the app context, by the browser following the redirect from PayPal, to the PayPal approve URL. It will automatically try to capture the payment and then change the order to completed. (ERP system is responsible for this task to handle in the background) The server redirects to the frontend PayPal success url.