Commerce settings reference

Who this is for. Developers and site administrators configuring a store. Look a setting up here: its label in the admin, its type and default, what it does, and whether staging and production should differ. How the settings are used in a build is on the guide's other pages.

True of every setting below, and not repeated in each entry:

• Where it is set: the module's settings page in the admin, under the label each entry gives. An entry whose label reads "Not shown in the admin" is set in .settings.json, described next.
• Scope: a stored setting belongs to the client account, so one value applies to every site of the account. A site that needs a different value sets it in a .settings.json file at the root of its repository, which takes precedence over the admin. For example, {"Checkouts": {"guestCheckout": {"value": false}}}.
• Environments: a value saved in the admin is stored in that environment's database. A value set on staging is not on production until someone sets it there too. A value in .settings.json travels with the repository instead. The Per environment row says when the values should differ.
• Key: the name used to read the setting, Module.key.

Reading a setting in a template

$_config reads any setting except those of the Environment, Mailer and Documentation modules, which return ***. Test a switch by its truth, as here:

{if $_config->get('Checkouts.guestCheckout')}
  <p>You can check out as a guest.</p>
{/if}

{% if _config.get('Checkouts.guestCheckout') %}
  <p>You can check out as a guest.</p>
{% endif %}

Carts

Carts.lifetime

Admin label	Lifetime
Type	Number, in seconds
Default	15552000 (180 days)
Effect	How long a guest cart is kept after its last change before the platform's clean-up job deletes it. It is also the lifetime of the cart cookie, set again on every visit that loads the cart and by the restore link. A cart whose person has a login is kept.
Per environment	No

Carts.abandonedThreshold

Admin label	Abandoned Threshold
Type	Number, in seconds
Default	3600 (one hour)
Effect	How long a cart must go unchanged before it counts as abandoned. A cart qualifies with items, a person with an email address, and no checkout in progress. A job that runs every five minutes fires the Abandoned event once for each qualifying cart; a later change makes the cart eligible again. See abandoned carts.
Per environment	Lower it on a test site to see an abandoned-cart job run without waiting an hour

Carts.abandonedBatchSize

Admin label	Not shown in the admin
Type	Number
Default	200
Effect	The most carts the abandoned-cart job examines in one run. A backlog is worked through over several runs.
Per environment	No

Checkouts

Checkouts.guestCheckout

Admin label	Enable guest checkout
Type	Switch
Default	On
Effect	On, a shopper can check out without signing in, and the guest's email address creates a person with no login; see guest and account checkout. Off, checkout is for signed-in members: the checkout API answers 401 to anyone else, so send signed-out shoppers to sign in before they reach /checkout.
Per environment	No

Checkouts.recaptcha

Admin label	Require captcha
Type	Select: disabled (Disabled), checkbox (Enabled - Checkbox), invisible (Enabled - Invisible)
Default	checkbox
Effect	The reCAPTCHA v2 mode at payment. The purchase call checks the token, sent as _recaptchaToken, before anything else. The cart page and the checkout page receive _recaptcha to render the widget. disabled skips the check and leaves _recaptcha unset.
Per environment	No. The reCAPTCHA keys are environment configuration, set by Core dna

Checkouts.lifetime

Admin label	Checkout Lifetime
Type	Number, in seconds
Default	1800 (30 minutes)
Effect	How long a checkout still attached to its cart is kept without activity. After that a background job deletes it, its cookie expires with it, and the shopper starts a new checkout from the cart. Once a payment has been sent whose result comes later (an authentication challenge, a redirect to the provider, a pending payment or a partial payment), the checkout is split from its cart and kept for Checkouts.standaloneLifetime instead, so a later payment result still completes it into an order. See from cart to order.
Per environment	No

Checkouts.standaloneLifetime

Admin label	Not shown in the admin
Type	Number, in seconds
Default	31536000 (365 days)
Effect	How long a checkout split from its cart is kept after its last change. A checkout is split when a payment is sent whose result comes later: an authentication challenge, a redirect to the provider, a pending payment or a partial payment. The paid-for items leave the cart, which keeps anything else, and the checkout waits on its own for the result. That result can arrive days later, by webhook, and still completes the checkout into an order; see webhooks. The clean-up job deletes split checkouts older than this, separately from ordinary ones.
Per environment	No

Checkouts.defaultCheckoutType

Admin label	Not shown in the admin
Type	Text
Default	single
Effect	The checkout POST /checkout starts: single, the single-page checkout. Keep the default.
Per environment	No

Orders

Orders.orders.numberTemplate

Admin label	Order number template
Type	Text
Default	{SEQ}
Effect	The pattern for order numbers. {SEQ} is the sequence, {SEQ:6} pads it to six digits, and {DATE} is today as 20261005, which restarts the sequence every day. Changing the template starts the sequence again at 1. Include {SEQ} in every template: it is the part that makes each order number unique. See order numbers.
Per environment	Optional. A different prefix on staging keeps its order numbers from being mistaken for real ones

Orders.orders.metadataFieldListing

Admin label	Metadata Fields
Type	Several order metadata fields
Default	None
Effect	Which order metadata fields appear as columns in the admin's list of orders, such as a purchase-order number. It changes nothing on the website or in the API.
Per environment	No

Shipping

Shipping.defaultShippingCategory

Admin label	Default shipping category
Type	One shipping category
Default	None
Effect	The shipping category used for a product that has none; a variant uses its parent's. A shipping method offers rates for an order when every item's shipping category, its own or this default, is among the method's categories, so set a default to cover products without one. See why a method does not appear.
Per environment	No

Shipping.rates.lifetime

Admin label	Lifetime, under Rate settings
Type	Number, in seconds
Default	3600 (one hour)
Effect	How long a shipping rate is valid after it is created. A checkout is ready for payment while its selected rate is valid, so create shipping again for a shopper who comes back after longer than this; see rate lifetime.
Per environment	No

Taxes

Taxes.enabled

Admin label	Enabled
Type	Switch
Default	Off
Effect	Off, no tax is calculated: tax totals are zero, and nothing is sent to a provider after payment. On, every checkout is taxed by a provider; set the default warehouse and the default provider (below) before switching it on.
Per environment	No

Taxes.defaultWarehouse

Admin label	Default warehouse
Type	One warehouse
Default	None
Effect	Its address is the origin (ship-from) address in a tax calculation when no other warehouse is given, and the destination too when the zone resolves to the warehouse. With tax on, choose a warehouse that has an address.
Per environment	No

Taxes.fallbackProvider

Admin label	Default provider
Type	One tax provider
Default	None
Effect	The provider that taxes an address no tax zone matches. Set it to an enabled provider whenever tax is on, so every address has one; the message "Could not determine tax provider" means an address matched no zone and found no default provider. See the tax providers.
Per environment	Yes: a sandbox or test provider on staging, the live provider on production. Check it after any copy of settings between environments

Taxes.zoneAddress

Admin label	Zone resolves to
Type	Select: shipping (Shipping address), billing (Billing address), warehouse (Warehouse address)
Default	shipping
Effect	Which address chooses the tax zone and is sent to the provider as the destination. shipping is the delivery address sent with the shipping call, or the checkout's delivery address before shipping exists. With billing, send the billing address early in the checkout, before shipping.
Per environment	No

Taxes.pricingIncludesTax

Admin label	Pricing includes tax
Type	Switch
Default	Off
Effect	Tells the tax provider, with every calculation, that catalogue prices already include tax. See inclusive prices.
Per environment	No

Products

Products.defaultCurrency

Admin label	Default currency
Type	One currency
Default	US Dollar
Effect	The currency every product is priced in first. It is always one of the supported currencies, and GET /cdna-api/common/currency/default returns it.
Per environment	No. Set it before any prices are entered

Products.supportedCurrencies

Admin label	Supported pricing currencies
Type	Several currencies
Default	None, so the default currency only
Effect	The currencies prices can be given in, in addition to the default, which is always included. GET /cdna-api/common/currencies/supported lists them. A cart's currency is set when its first item is added, and a product joins a cart when it has a price in the cart's currency; see currencies.
Per environment	No

Products.multiCurrency

Admin label	Use multi currency for products
Type	Switch
Default	Off
Effect	Shows a price per currency in the product editor. It changes only the admin form: switching it off keeps the prices already entered, and the cart prices from whatever is stored.
Per environment	No

Products.useTags

Admin label	Use tags for products
Type	Switch
Default	On
Effect	Shows the tags field in the product editor. Switching it off keeps existing tags.
Per environment	No

Products.generateInSitemap

Admin label	Generate products in sitemap
Type	Switch
Default	On
Effect	Whether products are listed in the generated sitemap.
Per environment	No

Products.interest.allowGuests

Admin label	Allow guests to register interest in products, under Expression of interest
Type	Switch
Default	Off
Effect	On, a visitor with no account can register interest in a product with an email address. An address the site does not know gets a new person record; an address that belongs to an account is refused, and the visitor signs in instead. See back-in-stock requests.
Per environment	No

Products.interest.groups

Admin label	Groups for people registering interest, under Expression of interest
Type	Several groups
Default	None
Effect	The groups a person created by an expression of interest is added to. People who already exist keep their groups.
Per environment	No

Products.interest.recaptcha

Admin label	reCAPTCHA for guests registering interest, under Expression of interest
Type	Select: disabled (Disabled), checkbox (v2 Checkbox), invisible (v2 Invisible)
Default	checkbox
Effect	The reCAPTCHA v2 mode for a guest registering interest; a signed-in member is never challenged. The product page receives the widget's settings as _recaptcha, and the site's form renders the widget for guests and posts its token as g-recaptcha-response.
Per environment	No. The reCAPTCHA keys are environment configuration, set by Core dna

Products.interest.stockThreshold

Admin label	Stock threshold for back in stock notifications, under Expression of interest
Type	Number
Default	0
Effect	A product fires its BackInStock event when its available stock, summed across every warehouse, rises above this quantity. A job on the event emails the people waiting for the product; see when stock comes back.
Per environment	No

Discounts

Discounts.quantityCountScope

Admin label	Order quantity counting scope for discount conditions
Type	Select: all (All currencies), currency (Active cart currency only)
Default	all
Effect	Whether a discount's or code's maximum uses, and order-count conditions, count across all currencies or only in the cart's currency. Amount thresholds always count only in the cart's currency. Uses are counted from checkouts as well as orders, so an open checkout holds a use until it ends.
Per environment	No

Configured elsewhere

A store also depends on settings outside the commerce modules:

• Globals.security.cspPolicy, "CSP policy" under Globals › Security. Default script-src 'self' https://cdnjs.cloudflare.com 'nonce-%nonce%'. Add Stripe's and PayPal's script hosts to it, keeping the %nonce% placeholder. See Content Security Policy.
• Environment configuration, set by Core dna for each environment, not in the admin, and never readable from a template: the platform's Stripe keys (Environment.stripe.test.* and Environment.stripe.live.*, chosen by a Stripe payment method's Test Mode), the PayPal Donate salt (Environment.paypalDonate.salt), which PayPal Donate uses, and the reCAPTCHA v2 keys (Environment.recaptcha.v2.*).
• Payment methods and tax providers are records, not settings. Their fields are on the provider reference.