Documentation

Get started with commercetools InStore

Use this guide to set up commercetools InStore and understand its functionality.

Overview

This guide explains how to set up and use the components required to run the InStore colleague app in your physical store locations. You can use this guide to set up a demo project or as a reference when setting up your test and production environments.

Prerequisites

You need to obtain the following information from your commercetools representative:

Additionally, developers can use the implementation overview to learn how to define the connections to the InStore integration server.

Set up connectivity to the InStore Center

Access the InStore Center

The InStore Center is an administration portal where you customize your business rules and other configurations. This application is maintained and hosted by commercetools, and you are granted access to maintain your own settings. You can access the InStore Center using a unique URL and credentials that you received from your commercetools contact person.

The InStore Center is not localized and is always presented in US English (en-US). Date and time information in this application is obtained from the commercetools server that hosts your instance of the InStore Center. The InStore Center application is optimized for desktop use and is not mobile-responsive.

commercetools support does not have access to your InStore Center instances unless you provide them credentials and grant them access.

Provide access to others on your team

If you are an administrator in the InStore Center, you can add more administrators to the environments to which you have access. For information about how to do this, see Users.

Set up the tenant environment

An environment (also known as the tenant environment) is a collection of physical store locations that share a currency, an integration server, a default locale (language), and a list of roles. You can create a test environment and a production environment for each country where you do business. Your Composable Commerce Project can interact with multiple environments, and you must request at least one environment for each currency where you do business.

Only one currency can be set per environment, and this cannot be changed after the environment is saved. In contrast, the locale that is set at the environment level can be overridden for a location. You set up each environment with the connection details that match your Composable Commerce Project, your integration server, and the InStore APIs. For information about setting up an environment, see Environment.
You need to use the InStore Center to provide connection details for an environment's integration with your Composable Commerce Project, define its business rules, and more. For more information about environments, see Environment.

If you use password management software, always review environment settings before saving them as these can unintentionally overwrite fields.

You can view daily, weekly, and monthly statistics for an environment on its dashboard.
Remember to include your InStore colleague app URL on the Approved URLs tab within the Environment record to allow your environment to access the app.

Set up a store role

You must set up at least one store role before you can activate the environment. Store roles are shared across all locations in the environment. You specify the role names and the combination of permissions you want to give individuals or groups of InStore colleague app users. InStore supports only the permissions that are listed in InStore Center. For more information about these permissions and how to set them up, see Store Roles.

You must also add the store role to your integration server and API. When setting up your authentication management system for InStore, pass the exact names of the store roles you create in the InStore Center.

Add locations and devices

A location is a physical store where the InStore colleague app is used. A location belongs to one environment and contains many devices that are used to process sales and returns.

Locations can only be added to an environment that has a status of Active and cannot be used until you add devices to it. The location remains in a Pending mode until you add its devices.
You can add a location and its devices via the InStore device CLI or manually add a location and then manually set up devices for it.

Devices include printers, cash drawers, workstations, PEDs, scanners, and a safe. Each store requires a safe, which can be a designated cash drawer.

For information about the devices you can use with InStore, see Hardware requirements.

Add a location via the InStore device CLI

We offer the InStore device CLI, which is a Node.js-based command-line tool that simplifies the process of setting up locations and their associated devices. You create multiple locations and devices from a JSON or YAML configuration file.

Manually add a location

The InStore Center has a user interface where you can add a single location. When you add the location, it is Pending until you set up devices for it. For more information about manually adding a location, see Location.

Manually set up devices for a location

A location cannot be activated until you set it up with at least one printer, cash drawer, workstation, and safe. For information about setting up devices using the InStore colleague app, see Devices.

Adding devices using the InStore colleague app

For the benefit of your store associates, we recommend that you pre-program the InStore colleague app URL into a locked browser for direct access.

When you access the InStore colleague app for a location with a status of Pending, the only menu option available is Manage devices. Your assigned store role must include the DeviceManagement permission to add and manage devices. Your authentication management system must assign users to the role, as store-user management is outside the scope of InStore.
  1. Access your specific InStore colleague app link. This can be a test instance that has been created using our hosted modular store or a purpose-built front-end app. The URL uses the following format:
{host site}/{environment label}/{location ID}/{workstation ID}
When you access the colleague app for a location with a status of Pending, no workstations exist yet. Use the workstation ID 01 in your URL.
The workstation ID portion of the URL is intended to be claimed by a single, consistent physical workstation device. If during testing you access an identical colleague app URL on multiple devices, append ?forceClaim=true to the end of the URL to release the claim made by the previous device, for example:
https://your-instore-app.com/test-env/12345/01?forceClaim=true
Use the ?forceClaim=true query parameter only when you need to release a workstation claim, such as when you are testing the same workstation URL on multiple devices or browsers. In normal operation, this parameter is not required and should not be used unless you specifically need to override the device claim.
  1. On the Enter Credentials page, enter your User ID and Password as determined by your authentication management system.
  2. Click Log In.

Register devices

Add and maintain the following devices in the colleague app:

Activate the location

When you have added sufficient devices to the InStore Center, the Activate Location button is available. Click it to activate the location and re-login to view additional menu items that your assigned role may unlock.

Confirm the selected safe

You must return to the InStore Center to complete the final step of confirming your selected safe to finish activating the location. To confirm the safe, do the following:

  1. In the InStore Center, select Locations.
  2. Find the newly activated location and select Edit.
  3. In the Safe field, select the safe you want to use for this location.
  4. Save your changes.

Customize via the InStore Center

The InStore Center contains the settings you use to specify your business rules and enforce policies at an environment, location, and workstation level.

Parameter sets and versioning

You need to maintain one or more parameter sets to inform InStore of your business rules. For a full list of parameters you can use, see Administration Parameters.

Some parameters may not be visible in the InStore Center because they are opt-in features that you need to contact us to activate.

The history of the parameter versions in an environment is tracked in the Parameter History of the InStore Center.

Reference lists

You can use reference list entries (also called reason codes) for financial reporting buckets, or tracking motivation for customer or colleague actions. For example, to track the reason why a particular item was returned or why cash was removed from the cash drawer. This information can be used to improve customer service and assist with loss prevention research.

InStore lets you define reason codes, which are not available at other points in the workflow. However, you can control the selections that users have and whether they must make a deliberate selection.

Verify that the default reference list entries are correct for your business. For information about adding additional codes in the InStore Center, see Reference Lists.

Receipts

InStore produces receipts for core activities including payments, refunds, and cash management. It can also produce gift receipts and return vouchers. An SVG image of the receipt template is printed to the screen and the corresponding data to populate print, email, or text receipts is sent to the receipt server.

You need to customize receipt text, image, data, and appearance by creating one or more receipt template sets, which you can then assign to an environment or location. You must create a different set for each environment. Templates pull from transaction details and from many values you have already entered in the Location record.
Make sure you test the receipt print server and that your receipts print correctly. For more information, see Managing and displaying receipt data.

Track and monitor

After you run transactions using the InStore colleague app, you can use the following in the InStore Center to track your activities:

Explore InStore

Prepare to receive cash

If your location accepts cash, prepare to receive it by doing the following:

  1. Go to the InStore colleague app.
  2. On the left-hand navigation menu, click Manage Cash, then click Cash Count.
  3. Select to count the default cash drawer by selecting the Opening Count Reason, then click NEXT.
  4. Type numbers of bills and coins that total more than the current reserve amount. You can find the reserve amount in the parameter setting Drawer_Reserve_Amount for the parameter set that is currently active at this location.
  5. Click NEXT.
  6. Click ACCEPT.

The workstation is then ready to process take-with sales paid with cash.

Next steps

Run a test transaction to ensure you are set up correctly by doing the following:

  • Ring up sales with all tender types and combinations that you want to accept.
  • Run all the cash-management activities you plan to use, including your end-of-day.
  • Generate each type of receipt you want to use.
You can also further explore InStore features in a way that suits your needs.