Static Bundles

Table of contents

• Overview
• Technology
• Features
  • Bundles List
  • Bundle Creation
  • Bundle Details
    • General
    • Images
    • Prices
• Architecture
  • Product
  • Product Types
    • StaticBundleParent
    • StaticBundleChildVariant
    • Sample Bundle
• Configuration
• Installation
• Development
  • Start the development server
  • Troubleshooting
    • graphql_error.invalid_token error
    • Do’s and Don’ts
  • Linting & Formatting
    • Formatting code
    • Linting code
      • Linting GraphQL Queries
      • Generating CTP GraphQL schema
  • Git Hooks
• Tests
• Build & Deployment
  • Registration with Merchant Center
    • Configuration Values
• Complete the Solution: Your Implementation Responsibilities
• Support

Overview

The static bundles solution handles the concept of putting together multiple related products for a total-sum price. An example static bundle is selling a camera, bag, and SD card for a single bundled price. The customer purchases a single bundle and then receives two or more distinct inventory items as selected by merchandising.

This process has been achieved by creating a new product with a specific type that references all the items within the bundle. On adding this new item to the cart, an API extension platform-extension-static-bundles is executed for cart requests to manage the child items during checkout. The final order includes the bundle items with pricing and a list of child line items for fulfillment.

The Merchant Center custom application in this solution assists merchandisers in creating and managing static bundles.

Technology

• ReactJS
• Apollo & GraphQL
• Merchant Center Application Kit
• UI Kit - Merchant Center component library
• Yarn - Package manager
• Jest - Test runner
• Enzyme - React testing utility
• Prettier - Code formatter
• ESLint - JS, CSS, and GraphQL linter

Features

Bundles List

The landing page for the static bundles custom application is a list displaying the static bundles within the commercetools project.

• Pagination
  • Default page size of 30,
  • Displayed when the number of static bundles exceeds the page size
• Sorting
  • Sortable columns are Name, Price, and Last Modified
  • Initial sort is Last Modified in descending order (most recent to least recent bundles)
• Search for a bundle using product projections search
• Filter
  • By bundle category (must be set on bundle from Merchant Center Products application. Ex: https://mc.us-central1.gcp.commercetools.com/{projectKey}/products/{bundleId})
  • By product variant within bundle

Bundle Creation

• Single step to create a static bundle with basic information
• Search for a product variant using product projections search
• Automatic slug creation based on the name of the bundle, which can be modified to suit your needs

Bundle Details

Manage bundle information, add images, and determine pricing strategies.

• Manage the bundle’s published status
• Delete unpublished bundle

General

Edit the bundle’s general information.

Images

• Add image(s) to the bundle from the images of the bundle’s components (product variants)
• Add image(s) directly to the bundle via Merchant Center
• Remove images
• Manage other image properties via Merchant Center

Prices

View the prices of the bundle components in various scopes to determine its prices.

• View bundle component prices in different price scopes
• Add a price via Merchant Center
• View prices via Merchant Center

Architecture

Product

A bundle is a commercetools product with only a master variant. The bundle components are stored as attributes of the master variant in accordance with the bundle product types.

Product Types

StaticBundleParent

• products - Array of StaticBundleChildVariant - Required
  The components of the bundle
• productsSearch - Array of String - Required
  The bundle components stringified as {productId}/{variantId} and used to filter the bundle list

StaticBundleChildVariant

A bundle component, which is a product variant.

• variant-id - Number - Required
  The ID of the product variant.
• quantity - Number - Required
  The number of the component within the bundle.
• sku - String
  The SKU of the product variant. Used for display purposes within the product search when viewing a bundle.
• product-ref - Product Reference
  A reference to the product associated with the bundle product variant. Used to create the product search value.
• product-name - LocalizedString
  The name of the product associated with the bundle product variant. Used for display purposes within the product search when viewing a bundle.

Note: If any of the underlying values of the selected product variant or product change, the attribute values will not be updated until the bundle component in question is re-selected and saved on the bundle with the new values.

Sample Bundle

Configuration

A terraform script initializes the commercetools project for using static bundles. Prior to using static bundles, this terraform script must be executed against the commercetools project and will deploy:

• Static Bundle Product Type – For creating new bundles
• Nested Product Type – For managing 1…n variant references from a static bundle
• Custom Line Item Type – For managing cart process

Installation

Simply run yarn from the repository root to install the application’s dependencies.

Development

Start the development server

Run the following command to start the development server and launch the application:

yarn start

If this is the first time running the application locally, open an .env.local file. Based on your region, you may find it necessary to modify the values in the env file.

Troubleshooting

graphql_error.invalid_token error

Log out of Merchant Center. Log back in, then return to the custom application and reload.

Do’s and Don’ts

• Don’t use the application development login screen to authenticate.
• Do make sure you are logged in to Merchant Center before developing or running a custom application.

Linting & Formatting

Formatting code

Run the following command to format JS, CSS, JSON and GraphQL files

yarn format

Linting code

Run the following command to lint JS, CSS, and GraphQL files

yarn lint

Linting GraphQL Queries

A prerequisite for linting GraphQL queries is generating a schema.graphql file, which contains the Types exposed by CTP API. Every time the API introduces new Types, Queries or Mutations, the local schema.graphql must be updated.

Generating CTP GraphQL schema

1. If you haven’t done so already, create an API client under Settings -> Developer Settings in Merchant Center for your project
2. Generate an access token using the Client Credentials flow
3. Export both your Merchant Center project key and generated access token as environment variables
4. Retrieve schema with graphql-cli

export PROJECT_KEY={project_key}
export AUTH_TOKEN={access_token}
npx graphql-cli get-schema

Git Hooks

Git hooks are configured using Husky. The root workspace runs all workspace hooks using Lerna (example repository). The hooks are configured as follows:

• Pre-commit: JS, CSS, and GraphQL files are linted (ESLint/Stylelint) and formatted (Prettier). Fixes are automatically added to Git.
• Commit Message: Commit messages are linted against the conventional commit format using commitlint

Tests

Run the following command to run the tests:

yarn test

To run the tests in watch mode:

yarn test:watch

To run the tests with coverage:

yarn test:coverage

Build & Deployment

Run the following command to build the production bundles with webpack:

yarn build

Please check for deployment examples documentation here.

NOTE: Be sure to set the env vars for the placeholders in custom-application-config.mjs.

• Example: For AWS deployment, env variables can be set using the file env.aws. For other deployments, duplicate the file and set values accordingly.

For more information on how to use .env files, check official documentation.

Registration with Merchant Center

After deploying the custom application, it needs to be registered with a Merchant Center project.

Configuration Values

• Main Route Path: bundle-manager
• Link Permissions: Manage Products, View Products

Complete the Solution: Your Implementation Responsibilities

To complete the bundles solution, you will need to supply a product detail page (PDP) for the static bundle products in your frontend implementation. Depending on your use case, the PDP can utilize the bundle attributes to display the individual bundle components, or you can rely on the bundle product’s images to convey that information. Using the latter option means that you can use the same PDP implementation to display all of your commercetools products.

Support

Please create an issue in the repository for all support requests related to the static bundles solution.