Configuring Commerce

You are viewing documentation for an unreleased version of Craft Commerce. Please be aware that some pages, screenshots, and technical reference may still reflect older versions.

Commerce supports a number of settings. Like Craft’s config settings, you can override their default values in a config/commerce.php file.

return [
    'purgeInactiveCartsDuration' => 'P1D',
];

# Aliases

Commerce adds these aliases on top of those provided by Craft.

Alias	Description
`@commerceLib`	The path to `vendor/craftcms/commerce/lib/`

# Environmental Configuration

Some Commerce settings should be defined on a per-environment basis.

System Settings
- General Settings
  - Email
    - Status Email Address
    - From Name
  - Subscription Settings
    - Billing detail update URL

# PHP Constants

# `COMMERCE_PAYMENT_CURRENCY`

This constant can be used to lock a valid payment currency ISO code, which otherwise defaults to the primary currency.

# Project Config

Craft Commerce stores the following items in the Craft project config:

Commerce general settings
Email settings
PDF settings
Gateways settings
Order field layout
Order Statuses
Product types
Fields and field groups
Subscription field layout

Not everything should be stored in the project config. Some items are considered content, which will change in production—meaning they’re not stored in the project config:

Discount promotions
Sales promotions
Shipping categories
Shipping zones
Shipping methods and rules
Subscription plans
Subscriptions elements
Tax categories
Tax zones
Tax rates
Order elements
Products & Variant elements

# Config Settings

# System

# `defaultView`

Allowed types: string (opens new window)
Default value: 'commerce/orders'
Defined by: Settings::$defaultView (opens new window)
Since: 2.2

Commerce’s default control panel view. (Defaults to order index.)

# `emailSenderAddress`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$emailSenderAddress (opens new window)

Default email address Commerce system messages should be sent from.

If null (default), Craft’s MailSettings::$fromEmail (opens new window) will be used.

# `emailSenderAddressPlaceholder`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$emailSenderAddressPlaceholder (opens new window)

Placeholder value displayed for the sender address control panel settings field.

If null (default), Craft’s MailSettings::$fromEmail (opens new window) will be used.

# `emailSenderName`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$emailSenderName (opens new window)

Default from name used for Commerce system emails.

If null (default), Craft’s MailSettings::$fromName (opens new window) will be used.

# `emailSenderNamePlaceholder`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$emailSenderNamePlaceholder (opens new window)

Placeholder value displayed for the sender name control panel settings field.

If null (default), Craft’s MailSettings::$fromName (opens new window) will be used.

# `showEditUserCommerceTab`

Allowed types: boolean (opens new window)
Default value: true
Defined by: Settings::$showEditUserCommerceTab (opens new window)
Since: 4.0

Whether the Commerce Tab should be shown when viewing users in the control panel.

# Cart

# `activeCartDuration`

Allowed types: mixed
Default value: 3600 (1 hour)
Defined by: Settings::$activeCartDuration (opens new window)
Since: 2.2

How long a cart should go without being updated before it’s considered inactive.

See craft\helpers\ConfigHelper::durationInSeconds() (opens new window) for a list of supported value types.

# `allowCheckoutWithoutPayment`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$allowCheckoutWithoutPayment (opens new window)
Since: 3.3

Whether carts are can be marked as completed without a payment.

# `allowEmptyCartOnCheckout`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$allowEmptyCartOnCheckout (opens new window)
Since: 2.2

Whether carts are allowed to be empty on checkout.

# `autoSetCartShippingMethodOption`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$autoSetCartShippingMethodOption (opens new window)

Whether the first available shipping method option should be set automatically on carts.

# `autoSetNewCartAddresses`

Allowed types: boolean (opens new window)
Default value: true
Defined by: Settings::$autoSetNewCartAddresses (opens new window)

Whether the user’s primary shipping and billing addresses should be set automatically on new carts.

# `autoSetPaymentSource`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$autoSetPaymentSource (opens new window)
Since: 4.2

Whether the user’s primary payment source should be set automatically on new carts.

# `cartVariable`

Allowed types: string (opens new window)
Default value: 'cart'
Defined by: Settings::$cartVariable (opens new window)

Key to be used when returning cart information in a response.

# `loadCartRedirectUrl`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$loadCartRedirectUrl (opens new window)
Since: 3.1

Default URL to be loaded after using the load cart controller action.

If null (default), Craft’s default siteUrl will be used.

# `purgeInactiveCarts`

Allowed types: boolean (opens new window)
Default value: true
Defined by: Settings::$purgeInactiveCarts (opens new window)

Whether inactive carts should automatically be deleted from the database during garbage collection.

You can control how long a cart should go without being updated before it gets deleted purgeInactiveCartsDuration setting.

# `purgeInactiveCartsDuration`

Allowed types: mixed
Default value: 7776000 (90 days)
Defined by: Settings::$purgeInactiveCartsDuration (opens new window)

Default length of time before inactive carts are purged. (Defaults to 90 days.)

See craft\helpers\ConfigHelper::durationInSeconds() (opens new window) for a list of supported value types.

# `updateCartSearchIndexes`

Allowed types: boolean (opens new window)
Default value: true
Defined by: Settings::$updateCartSearchIndexes (opens new window)
Since: 3.1.5

Whether the search index for a cart should be updated when saving the cart via commerce/cart/* controller actions.

May be set to false to reduce performance impact on high-traffic sites.

Setting this to false will result in fewer index update queue jobs, but you’ll need to manually re-index orders to ensure up-to-date cart search results in the control panel.

# `validateCartCustomFieldsOnSubmission`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$validateCartCustomFieldsOnSubmission (opens new window)
Since: 3.0.12

Whether to validate custom fields when a cart is updated.

Set to true to allow custom content fields to return validation errors when a cart is updated.

# Orders

# `freeOrderPaymentStrategy`

Allowed types: string (opens new window)
Default value: 'complete'
Defined by: Settings::$freeOrderPaymentStrategy (opens new window)

How Commerce should handle free orders.

The default 'complete' setting automatically completes zero-balance orders without forwarding them to the payment gateway.

The 'process' setting forwards zero-balance orders to the payment gateway for processing. This can be useful if the customer’s balance needs to be updated or otherwise adjusted by the payment gateway.

# `minimumTotalPriceStrategy`

Allowed types: string (opens new window)
Default value: 'default'
Defined by: Settings::$minimumTotalPriceStrategy (opens new window)

How Commerce should handle minimum total price for an order.

Options:

'default' rounds (opens new window) the sum of the item subtotal and adjustments.
'zero' returns 0 if the result from 'default' would’ve been negative; minimum order total is 0.
'shipping' returns the total shipping cost if the 'default' result would’ve been negative; minimum order total equals shipping amount.

# `orderReferenceFormat`

Allowed types: string (opens new window)
Default value: '{{number[:7]}}'
Defined by: Settings::$orderReferenceFormat (opens new window)

Human-friendly reference number format for orders. Result must be unique.

See Order Numbers.

# `pdfAllowRemoteImages`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$pdfAllowRemoteImages (opens new window)

Whether to allow non-local images in generated order PDFs.

# `pdfPaperOrientation`

Allowed types: string (opens new window)
Default value: 'portrait'
Defined by: Settings::$pdfPaperOrientation (opens new window)

The orientation of the paper to use for generated order PDF files.

Options are 'portrait' and 'landscape'.

# `pdfPaperSize`

Allowed types: string (opens new window)
Default value: 'letter'
Defined by: Settings::$pdfPaperSize (opens new window)

The size of the paper to use for generated order PDFs.

The full list of supported paper sizes can be found in the dompdf library (opens new window).

# `requireBillingAddressAtCheckout`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$requireBillingAddressAtCheckout (opens new window)

Whether a billing address is required before making payment on an order.

# `requireShippingAddressAtCheckout`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$requireShippingAddressAtCheckout (opens new window)

Whether a shipping address is required before making payment on an order.

# `requireShippingMethodSelectionAtCheckout`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$requireShippingMethodSelectionAtCheckout (opens new window)

Whether shipping method selection is required before making payment on an order.

# `updateBillingDetailsUrl`

Allowed types: string (opens new window)
Default value: ''
Defined by: Settings::$updateBillingDetailsUrl (opens new window)

URL for a user to resolve billing issues with their subscription.

The example templates include a template for this page (opens new window).

# `useBillingAddressForTax`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$useBillingAddressForTax (opens new window)

Whether taxes should be calculated based on the billing address instead of the shipping address.

# `validateBusinessTaxIdAsVatId`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$validateBusinessTaxIdAsVatId (opens new window)

Whether to enable validation requiring the businessTaxId to be a valid VAT ID.

When set to false, no validation is applied to businessTaxId.

When set to true, businessTaxId must contain a valid VAT ID.

This setting strictly toggles input validation and has no impact on tax configuration or behavior elsewhere in the system.

# Payments

# `allowPartialPaymentOnCheckout`

Allowed types: boolean (opens new window)
Default value: false
Defined by: Settings::$allowPartialPaymentOnCheckout (opens new window)

Whether partial payment can be made from the front end when the gateway allows them.

The false default does not allow partial payments on the front end.

# `gatewayPostRedirectTemplate`

Allowed types: string (opens new window)
Default value: ''
Defined by: Settings::$gatewayPostRedirectTemplate (opens new window)

The path to the template that should be used to perform POST requests to offsite payment gateways.

The template must contain a form that posts to the URL supplied by the actionUrl variable and outputs all hidden inputs with the inputs variable.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <title>Redirecting...</title>
</head>
<body onload="document.forms[0].submit();">
<form action="{{ actionUrl }}" method="post">
  <p>Redirecting to payment page...</p>
  <p>
    {{ inputs|raw }}
    <button type="submit">Continue</button>
  </p>
</form>
</body>
</html>

Since this template is simply used for redirecting, it only appears for a few seconds, so we suggest making it load fast with minimal images and inline styles to reduce HTTP requests.

If empty (default), each gateway will decide how to handle after-payment redirects.

# `paymentCurrency`

Allowed types: array (opens new window), null (opens new window)
Default value: null
Defined by: Settings::$paymentCurrency (opens new window)

ISO codes for supported payment currencies.

See Payment Currencies.

# Units

# `dimensionUnits`

Allowed types: string (opens new window)
Default value: 'mm'
Defined by: Settings::$dimensionUnits (opens new window)

Unit type for dimension measurements.

Options:

'mm'
'cm'
'm'
'ft'
'in'

# `weightUnits`

Allowed types: string (opens new window)
Default value: 'g'
Defined by: Settings::$weightUnits (opens new window)

Units to be used for weight measurements.

Options:

'g'
'kg'
'lb'

# Advanced Configuration

Additional customization of Commerce components is possible via application configuration. These settings must be added to your project’s config/app.php file, within the pluginConfigs block.

Cart cookies expire after one year, by default. Change this with the carts.cartCookieDuration property:

return [
    'components' => [
        'plugins' => [
            'pluginConfigs' => [
                'commerce' => [
                    'components' => [
                        'carts' => [
                            'cartCookie' => [
                                // Add custom key-value cookie params
                            ],
                            // Set the cart expiry to one month
                            'cartCookieDuration' => 2629800,
                        ],
                    ],
                ],
            ],
        ],
    ],
];

Configuring Commerce

# Aliases

# Environmental Configuration

# PHP Constants

# COMMERCE_PAYMENT_CURRENCY

# Project Config

# Config Settings

# System

# defaultView

# emailSenderAddress

# emailSenderAddressPlaceholder

# emailSenderName

# emailSenderNamePlaceholder

# showEditUserCommerceTab

# Cart

# activeCartDuration

# allowCheckoutWithoutPayment

# allowEmptyCartOnCheckout

# autoSetCartShippingMethodOption

# autoSetNewCartAddresses

# autoSetPaymentSource

# cartVariable

# loadCartRedirectUrl

# purgeInactiveCarts

# purgeInactiveCartsDuration

# updateCartSearchIndexes

# validateCartCustomFieldsOnSubmission

# Orders

# freeOrderPaymentStrategy

# minimumTotalPriceStrategy

# orderReferenceFormat

# pdfAllowRemoteImages

# pdfPaperOrientation

# pdfPaperSize

# requireBillingAddressAtCheckout

# requireShippingAddressAtCheckout

# requireShippingMethodSelectionAtCheckout

# updateBillingDetailsUrl

# useBillingAddressForTax

# validateBusinessTaxIdAsVatId

# Payments

# allowPartialPaymentOnCheckout

# gatewayPostRedirectTemplate

# paymentCurrency

# Units

# dimensionUnits

# weightUnits

# Advanced Configuration

# Cart Cookie Configuration

Was this page helpful?

# `COMMERCE_PAYMENT_CURRENCY`

# `defaultView`

# `emailSenderAddress`

# `emailSenderAddressPlaceholder`

# `emailSenderName`

# `emailSenderNamePlaceholder`

# `showEditUserCommerceTab`

# `activeCartDuration`

# `allowCheckoutWithoutPayment`

# `allowEmptyCartOnCheckout`

# `autoSetCartShippingMethodOption`

# `autoSetNewCartAddresses`

# `autoSetPaymentSource`

# `cartVariable`

# `loadCartRedirectUrl`

# `purgeInactiveCarts`

# `purgeInactiveCartsDuration`

# `updateCartSearchIndexes`

# `validateCartCustomFieldsOnSubmission`

# `freeOrderPaymentStrategy`

# `minimumTotalPriceStrategy`

# `orderReferenceFormat`

# `pdfAllowRemoteImages`

# `pdfPaperOrientation`

# `pdfPaperSize`

# `requireBillingAddressAtCheckout`

# `requireShippingAddressAtCheckout`

# `requireShippingMethodSelectionAtCheckout`

# `updateBillingDetailsUrl`

# `useBillingAddressForTax`

# `validateBusinessTaxIdAsVatId`

# `allowPartialPaymentOnCheckout`

# `gatewayPostRedirectTemplate`

# `paymentCurrency`

# `dimensionUnits`

# `weightUnits`