Get started with commercetools InStore

InStore Add-On
Ask about this Page
Copy for LLM
View as Markdown

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

This guide explains how to set up and use the components required to run the InStore POS 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:

  • Credentials and your organization's link for the InStore Center.

  • Credentials and your organization's link for the InStore POS.

  • Instructions for setting up your authentication management system to work with InStore.

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 commercetools.

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, 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 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 Project 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 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.

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 POS 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.

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 POS 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.

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

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.

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 POS, see Devices.

Add devices using the InStore POS

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

When you access the InStore POS 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 POS link. The URL uses the following format:

    {InStore POS URL}/{tenant ID}/{location ID}/{workstation ID}
    The InStore POS URL is the URL of the hosted InStore POS application in your region. The format is https://app.instore-pos.<region>.<cloudprovider>.com/. For example, https://app.instore-pos.<region>.<cloudprovider>.com/1971-6e97-2631-13cd/12345/01.
    Tenant ID is a 16-character alphanumeric value separated by hyphens and displayed in the InStore Center on the Integration Settings tab of the Environment page.
    When you access the InStore POS 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.
  2. On the Enter Credentials page, enter your User ID and Password as determined by your authentication management system.
  3. Click Log In.

Register devices

Add and maintain the following devices in the InStore POS:

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.

Configure payment options

You need to set up payment options to enable your store associates to process payments and refunds in the InStore POS.

After you set them up, you can assign payment options to as many locations and workstations as needed. For convenience, you can set payment options as default for all locations and workstations in the environment. If a location or workstation requires different payment options, you can assign a specific set there.

For more information about setting up payment options, see Build payment components.

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.

For UI theming, see Customize the InStore POS UI.

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 Manage and display receipt data.

Track and monitor

After you run transactions using the InStore POS, 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. Access the InStore POS.
  2. On the 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:

  • Search for a customer that exists in your commercetools Project.
  • 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.