Configure and deploy extensions

Use the Commerce Integration Layer CLI to configure, deploy, and manage extensions in production.

Before following the steps in this page, scaffold an extension.

Environment configuration and secrets

You can also manage these values in the Merchant Center.

Set configuration

Sets a value available to resolvers and handlers through ctx.config. Add --secret to encrypt and mask the value.

commercetools integration-layer config set MY_API_KEY secure-token-123 --secret

List configuration

Lists configuration values for the active Project. Secret values are masked.

commercetools integration-layer config list

Outbound HTTP domain allowlist

Patterns are bare hostnames (api.example.com) or suffix wildcards (*.example.com); quote wildcards so the shell does not expand them. The list also shows any operator deny patterns that take precedence; those are read-only from the CLI.

You can also manage these values in the Merchant Center.

List allowed domains

Lists external domains that sandboxed extensions can call with fetch. Allowed calls are still subject to outbound request limits.

commercetools integration-layer allowlist list

Add allowed domains

Adds bare hostnames or suffix wildcard patterns to the allowlist.

commercetools integration-layer allowlist add api.vendor.com '*.algolia.net'

Remove an allowed domain

Removes a hostname or pattern from the allowlist.

commercetools integration-layer allowlist remove api.vendor.com

Replace the allowlist

Replaces the complete allowlist with one or more hostnames or patterns. Requires at least one host; use remove instead to drop individual hosts.

commercetools integration-layer allowlist set api.vendor.com api.example.com

Project settings

Project settings are the display label of your Project and the default language, currency, and country. The Commerce Integration Layer uses the defaults for new shopper sessions.

You can also manage these values in the Merchant Center.

Get Project settings

Displays the label, the default language, currency, and country, and the region of the Project. The region is read-only. Add --json to print the label, language, currency, and country as JSON. The region isn't included.

commercetools integration-layer project-settings get

Update Project settings

Updates one or more settings. Pass at least one of --label, --language, --currency, or --country. Settings you don't pass keep their current values. If the Project has no stored value for a setting, you must pass that setting too.

commercetools integration-layer project-settings set --currency EUR --country DE
commercetools integration-layer project-settings set --label 'Acme Store' --language de-DE

The language, currency, and country must be ones that your commercetools Project supports. The command rejects other values and lists the ones you can use. Values are stored in the Project's spelling, so --country de saves DE.

Field visibility

Field visibility controls which of your Project's Custom Fields and Product Attributes storefronts can query through the Experience API. By default, every Custom Field and Product Attribute is public. When you hide a field, the Commerce Integration Layer removes it from the public schema, so storefronts can't see or select it. Your extensions can still read a hidden field with @requires.

When to use field visibility

Hide a field when it exists for internal integrations and storefronts have no reason to query it. Typical examples are a cost price, a margin band, or a partner reference stored in a Custom Field, or an internal code stored in a Product Attribute.

Field visibility fits when:

Your storefront queries the Experience API, and you don't want these fields to appear in its schema.
Your extensions still need the values. They can keep reading hidden fields with @requires.
You add fields over time and want to keep new internal fields out of the public schema from the start. You can hide a field before you create it.

Field visibility doesn't fit when:

You need to protect the data itself. Hiding a field keeps it out of the published API, but it doesn't control access to the data.
You need different visibility per shopper or Store. Rules name a type key and a field name only, so a field is either public or hidden for the whole Project.

Don't rely on field visibility to keep a value confidential.

How field visibility works

A hidden field is identified by a rule that names its type key and field name. For a Custom Field, the type key is the key of its Type. For a Product Attribute, it's the key of its Product Type, and you add --space attribute. You don't use the generated GraphQL names, because those can change when the rest of your Project's data model changes.

Every change republishes your Project's schema, which applies the rules. Because a hidden field disappears from the public schema, check first that no storefront query still selects it. A query that selects a hidden field fails validation, and the whole query returns an error instead of data, including the fields that are still public. In the Merchant Center, you can see the request count of each field for the last 30 days and filter for unused fields.

The following sections describe the CLI commands to manage field visibility.

You can also manage field visibility in the Merchant Center.

List field visibility

Lists every Custom Field and Product Attribute, grouped by type, and marks each one as hidden or visible. Add --hidden to list only hidden fields, or --json for machine-readable output. If a rule has no effect, for example because the field doesn't exist yet, the list says why.

commercetools integration-layer field-visibility list

Hide fields

Hides one or more fields of the same type.

commercetools integration-layer field-visibility hide --type-key internal-ops costPrice marginBand
commercetools integration-layer field-visibility hide --space attribute --type-key shoes internalCode

You can hide a field before you create it in commercetools. The rule is stored and applies as soon as the field exists, so the field is never public. This is the safest order for adding a field that storefronts shouldn't see.

Show fields

Removes the rules that hide one or more fields of the same type, so storefronts can query them again.

commercetools integration-layer field-visibility show --type-key internal-ops costPrice

Replace the hidden fields

Replaces the complete set of hidden fields with the fields in a JSON file. Pass - instead of a path to read from stdin. The file contains an array of fields, or an object with the array in hiddenFields. Duplicate entries are ignored, and an empty array makes every field visible. Use this command to keep the set in version control.

[
  { "space": "customField", "typeKey": "internal-ops", "fieldName": "costPrice" },
  { "space": "attribute", "typeKey": "shoes", "fieldName": "internalCode" }
]

commercetools integration-layer field-visibility set --file hidden-fields.json

A Project can have at most 500 hidden fields, and each type key and field name can be at most 256 characters long.

The show and set commands can make fields public, so they ask for confirmation. Pass --force to skip the prompt, which is required in non-interactive environments such as CI.

Republish the schema

Every change republishes your Project's schema, and the command waits for the result. On success, it prints The schema was republished. If the change was saved but the republish failed, the published schema doesn't reflect it yet: a field you hid may still be public, and a field you showed may still be hidden. In that case, the command exits with code 2. To retry, run set with the complete set of hidden fields. Running hide or show again doesn't retry, because the rules already match and the command saves nothing.

Publishing, rollouts, and status checks

You can also check the deployment status in the Merchant Center.

Publish an extension

Builds, validates, and deploys the extension bundle. Use --no-wait to exit before the health check or --wait-timeout to set its duration.

commercetools integration-layer extension push --wait-timeout 180

Check deployment status

Displays the newest stored bundle's version, size, upload time, and source revision, when recorded. It doesn't report lifecycle state, a failure reason, or which revision is actually served — see Checking what's live for where to find those.

commercetools integration-layer extension status

Environment configuration and secrets.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set configuration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

List configuration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Outbound HTTP domain allowlist.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

List allowed domains.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Add allowed domains.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Remove an allowed domain.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Replace the allowlist.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Project settings.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Project settings.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update Project settings.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Field visibility.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

When to use field visibility.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

How field visibility works.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

List field visibility.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Hide fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Show fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Replace the hidden fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Republish the schema.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Publishing, rollouts, and status checks.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Publish an extension.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check deployment status.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Further reading.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Environment configuration and secrets

Set configuration

List configuration

Outbound HTTP domain allowlist

List allowed domains

Add allowed domains

Remove an allowed domain

Replace the allowlist

Project settings

Get Project settings

Update Project settings

Field visibility

When to use field visibility

How field visibility works

List field visibility

Hide fields

Show fields

Replace the hidden fields

Republish the schema

Publishing, rollouts, and status checks

Publish an extension

Check deployment status

Further reading