SHOPin Logo
Skip to main documentation content

Set up Commercetools

The SHOPin storefront accelerator uses Commercetools as the e-commerce engine and optionally as the identity backend via an auth provider package. This guide covers Merchant Center setup, API credentials, environment variables, choosing the Commercetools data source, and optional commercetools-auth.

For the full variable list and inline comments, see How to setup SHOPin — Environment variables and .env.example. Repository clone, creating .env, installing dependencies, and running dev servers are covered in How to setup SHOPin — this page covers Commercetools-only steps.

Prerequisites

1. Get API credentials

  1. Log in to Merchant Center.
  2. Select your project (or create one).
  3. Go to Project settings → Developer settings → API clients.
  4. Create an API client (or use an existing one) with the scopes the BFF needs (for example manage products, cart, orders, customers—match what integrations/commercetools-api and related packages call).
  5. Copy:
    • Client ID
    • Client secret
    • Project key
    • API URL (for example https://api.{region}.commercetools.com)
    • Auth URL (for example https://auth.{region}.commercetools.com)

Regions are typically us-central1, europe-west1, and so on. Use the URLs shown in the Merchant Center for your project.

2. Add Commercetools values to root .env

Copy the Client ID, Client secret, Project key, API URL, and Auth URL from Merchant Center into the repository root .env using the COMMERCETOOLS_* names and order shown in .env.example. Replace region placeholders in the URLs with your project region (for example europe-west1). For how the root .env is created and how variables are grouped, see How to setup SHOPin — Environment variables.

3. Select Commercetools as the data source

The BFF picks the data source from environment configuration (DATA_SOURCE and related values). The exact names and allowed values are under config/constants in the accelerator repository.

The optional demo/ workspace includes DataSourceSelector (demo package overview): a component you can add to any page to switch data sources in the UI. The default storefront does not ship a data-source picker on the home page.

For production, use Remove demo functionality and set the data source only via environment configuration.

4. Auth provider (optional): commercetools-auth

If your deployment uses commercetools-auth as the Commercetools-oriented auth provider for login (customer sessions, and related flows):

  • The same Commercetools project and API client are usually enough; ensure the client has customer-related scopes (and any others required by your setup).

A separate Commercetools project for auth is only needed if you deliberately split auth from catalog.

5. Verify

Run npm run dev and check that catalog and related content are visible in the storefront. If not, use Troubleshooting below.

Troubleshooting

IssueWhat to check
401 UnauthorizedCOMMERCETOOLS_CLIENT_ID, COMMERCETOOLS_CLIENT_SECRET, COMMERCETOOLS_AUTH_URL; client not revoked or rotated.
403 ForbiddenAPI client scopes in Merchant Center versus what the BFF requests.
Wrong regionCOMMERCETOOLS_API_URL and COMMERCETOOLS_AUTH_URL match the project region.
Empty catalogProject has data in Merchant Center; active data source is commercetools-set (or the equivalent constant you use).

Related

Back to Integration setup