Composable Commerce extension

commercetools Frontend comes with out-of-the-box Composable Commerce extensions for B2C and B2B. With the extensions, you can fetch data from Composable Commerce and display it in your Frontend components.

Prerequisites

Access to your commercetools Frontend GitHub customer repository
Access to your commercetools Frontend Project from the Studio
Access to your Composable Commerce Project

Use the Composable Commerce extension

You can find the Composable Commerce extension in your commercetools Frontend project at this path packages/PROJECT_NAME/backend/commerce-commercetools.

If the commerce-commercetools extension is not available in your commercetools Frontend project, before proceeding with the following configuration, you must:

Clone the extension repository and add the code to your project:
- B2C extension
- B2B extension
Register the extension in your project.

To use the Composable Commerce extension you must:

Create an API client.
Configure your Composable Commerce extension.
Add data source schemas to the Studio.

Create an API client

When creating an API client, you need to select specific scopes depending if you are using the B2C or B2B extension.

For more information about API Clients, see Authorization and Scopes.

B2C API client

If you are using the B2C extension, select the following scopes when creating your API client:

In the Manage column: Cart discounts, Categories, Customer groups, Customers, Discount codes, Extensions, Order Edits, Orders, Payments, Products, Project Settings, Shipping methods, Shopping Lists, Tax categories, and Types
In the Manage My column: Orders, Payments, Profile, and Shopping Lists
In the Tokens column: Create Anonymous Token

B2B API client

If you are using the B2B extension, select the following scopes when creating your API client:

In the Manage column: Business units, Customers, and Shopping Lists
In the View column: Associate roles, Attribute groups, Business units, Cart discounts, Categories, Connectors, Connectors deployments, Customers, Customers groups, Discount codes, Messages, Order Edits, Orders, Payments, Product Selections, Products (all), Project Settings, Quote requests, Quotes, Shipping methods, Shopping Lists, Staged quotes, Standalone Prices, States, Stores, Tax categories, and Types
In the Manage My column: Business units, Orders, Payments, Profile, Quotes, Quote requests, and Shopping Lists
In the Tokens column: Create Anonymous Token

Configure the Composable Commerce extension

To configure your Composable Commerce extension, follow these steps:

Add the following project configuration fields to the project schema from the Studio.

Add Composable Commerce project configuration fieldsjson

{
  "name": "commercetools Composable Commerce extension",
  "fields": [
    {
      "label": "Project Key",
      "field": "EXTENSION_COMMERCETOOLS_PROJECT_KEY",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Client ID",
      "field": "EXTENSION_COMMERCETOOLS_CLIENT_ID",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Client Secret",
      "field": "EXTENSION_COMMERCETOOLS_CLIENT_SECRET",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Locale overwrite",
      "field": "EXTENSION_COMMERCETOOLS_LOCALE_OVERWRITE",
      "type": "string",
      "translatable": false,
      "required": false
    },
    {
      "label": "Authentication URL",
      "field": "EXTENSION_COMMERCETOOLS_AUTH_URL",
      "type": "string",
      "translatable": false,
      "required": false,
      "default": "https://auth.sphere.io"
    },
    {
      "label": "API URL",
      "field": "EXTENSION_COMMERCETOOLS_HOST_URL",
      "type": "string",
      "translatable": false,
      "required": false,
      "default": "https://api.sphere.io"
    },
    {
      "label": "Product ID field",
      "field": "EXTENSION_COMMERCETOOLS_PRODUCT_ID_FIELD",
      "type": "string",
      "translatable": false,
      "required": false,
      "default": "id"
    },
    {
      "label": "Category ID field",
      "field": "EXTENSION_COMMERCETOOLS_CATEGORY_ID_FIELD",
      "type": "string",
      "translatable": false,
      "required": false,
      "default": "id"
    }
  ]
}

Set the Composable Commerce configuration values from the Studio.
You can set different values for each environment.

Add data source schemas to the Studio

In your commercetools Frontend project, at the /packages/<project>/backend/schemas/dataSource path, you can find the following data source schemas:

The frontastic-product-list.json product list schema
The frontastic-product.json single product schema

To add the data source schemas to the Studio, follow these steps:

From the Studio home page or from the left navigation menu, go to Developer > Data sources.
Click Upload schema.
Search and select the JSON file to upload: the schema editor opens.
Click Publish to add the schema.

You can now use the Composable Commerce extension to fetch data to be displayed in the Frontend components.

Edit the Composable Commerce extension

You can edit the Composable Commerce extension to adapt it to your needs.

We recommend adding code to extend the extension's functionality rather than deleting or replacing anything. This way, when extension updates are released, they will be easier to apply.

To update your code, clone the Composable Commerce extension GitHub repository.