Documentation

Set up your Composable Commerce Project for InStore

Elevate, May 20-22-2025, Miami Beach, Florida

Set up your Project to use with commercetools InStore.

commercetools InStore customizable modules use Composable Commerce resources by referencing Composable Commerce resource key attributes. You must ensure that applicable resources you use have a value set in the key attribute.

API Clients

commercetools InStore uses a Composable Commerce API Client to connect to your Project. Therefore, you must create an API Client with the following scopes:
  • manage_customers
  • manage_orders
  • manage_payments
  • manage_shopping_lists
  • view_cart_discounts
  • view_categories
  • view_customer_groups
  • view_discount_codes
  • view_products
  • view_published_products
  • view_shipping_methods
  • view_stores
  • view_tax_categories
  • view_types
When configuring commercetools InStore, use the API Client to populate the Administration portal tab in Project settings that your InStore colleague app uses.

Taxes

For tax calculations, the customizable modules use the Composable Commerce Platform Tax Mode. You must define the Tax Rates for each country, and optionally, for each state or region where there are InStore locations. You must set the Tax Categories for each Product offered in the InStore colleague app.

For external tax calculations, you must create a custom module to handle the cart and checkout. If you use tax-inclusive pricing with external taxing, you might also need to customize the catalog.

Shipping Methods

Customizable modules create Carts that are configured for Multiple Shipping Methods. This configuration supports mixed Cart functionality—meaning the Cart includes both take-with and ship-to Orders.
Carts and Orders require a Shipping Method. Since all InStore-generated Carts and Orders use the same key, create a Shipping Method with key set to in-store. Typically, this Shipping Method has no cost associated with it because it is used for take-with orders. To support different fulfillment methods, you can define additional Shipping Methods.
If multiple fulfillment methods are available for an InStore order, eligible Shipping Methods are determined by the Cart Location.

Languages and currencies

Locales used in the Product Catalog, Customer, Cart, Order, and more should be configured in the Project. Each value in the LocalizedText fields is passed through to the InStore colleague app and set on the Order and Receipt.

Each InStore tenant is configured for a single currency. A Project supports multiple currencies—you can use one Project for multiple InStore tenants, but each InStore tenant can be configured to use only one Project.

Product catalog

InStore requires specific Product Attribute configuration on all Product Types in a Project.

To be discoverable in the InStore colleague app, each product variant/SKU must include the following Product Type attribute definitions and values.

Barcodes

The InStore scan-to-cart functionality requires a Product Attribute that contains unique values matching the alphanumeric representations of barcodes.

The Product Attribute must be of type Text and the isSearchable field set to true.
If the product catalog includes Product Variants that are not available in InStore or don’t have barcode values, the isRequired field must be set to false.

If a Product Variant/SKU does not have this value set, it will not be discoverable by the scan-to-cart functionality.

Example of single-barcode-value Product Attributejson
{
  "name": "barcode",
  "label": {
    "en": "barcode"
  },
  "inputTip": {
    "en": "Alphanumeric barcode (string) used for InStore scan lookups."
  },
  "isRequired": false,
  "type": {
    "name": "text"
  },
  "attributeConstraint": "Unique",
  "isSearchable": true,
  "inputHint": "SingleLine",
  "displayGroup": "Other"
}

Since multiple alphanumeric identifiers can be used for each SKU, the Product Attribute can alternatively be a set of text attributes.

Example of a set of text attributesjson
{
  "name": "barcodeSet",
  "label": {
    "en": "Barcode Set"
  },
  "inputTip": {
    "en": "Set of alphanumeric barcode (strings) used for InStore scan lookups."
  },
  "isRequired": false,
  "type": {
    "name": "set",
    "elementType": {
      "name": "text"
    }
  },
  "attributeConstraint": "Unique",
  "isSearchable": true,
  "inputHint": "SingleLine",
  "displayGroup": "Other"
}

Receipt text

InStore receipts draw localized text directly from the receipt-text attribute on the Product Variant. You must define this attribute and provide localized values for each Product Variant sold in a locale. For constraints on the values of this field, see Mapping Custom Fields in InStore.
Example of a receipt text attributejson
{
  "name": "receipt-text",
  "label": {
    "en": "Receipt Text"
  },
  "inputTip": {
    "en": "SKU level text to be shown on the receipt"
  },
  "isRequired": false,
  "type": {
    "name": "ltext"
  },
  "attributeConstraint": "None",
  "isSearchable": false,
  "inputHint": "SingleLine",
  "displayGroup": "Other"
}