Config Settings

In addition to the settings in Commerce → Settings, the config items below can be saved in a config/commerce.php file using the same format as Craft’s general config settings in config/general.php.

For example, if you wanted to change the inactive carts duration in dev environments but not on staging or production, you could do this:

return [
    // Global settings
    '*' => [
        // ...
    ],

    // Dev environment settings
    'dev' => [
        'purgeInactiveCartsDuration' => 'P1D',
        // ...
    ],

    // Staging environment settings
    'staging' => [
        // ...
    ],

    // Production environment settings
    'production' => [
        // ...
    ],
];

You can access the Commerce general settings model in your templates:

{% set settings = craft.commerce.settings %}

Here’s the full list of Commerce config settings:

#System

#defaultView

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

#emailSenderAddress

Default email address Commerce system messages should be sent from.

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

#emailSenderAddressPlaceholder

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

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

#emailSenderName

Default from name used for Commerce system emails.

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

#emailSenderNamePlaceholder

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

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

#showCustomerInfoTab

Whether the customer info tab should be shown when viewing users in the control panel.

#Cart

#activeCartDuration

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

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

#allowCheckoutWithoutPayment

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

#allowEmptyCartOnCheckout

Whether carts are allowed to be empty on checkout.

#autoSetCartShippingMethodOption

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

#autoSetNewCartAddresses

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

#cartVariable

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

#loadCartRedirectUrl

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

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

#purgeInactiveCarts

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

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

#purgeInactiveCartsDuration

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

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

#updateCartSearchIndexes

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.

::: warning 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

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

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

How Commerce should handle minimum total price for an order.

Options:

• 'default' rounds 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

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

See Order Numbers.

#pdfAllowRemoteImages

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

#pdfPaperOrientation

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

Options are 'portrait' and 'landscape'.

#pdfPaperSize

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.

#requireBillingAddressAtCheckout

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

#requireShippingAddressAtCheckout

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

#requireShippingMethodSelectionAtCheckout

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

#updateBillingDetailsUrl

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

::: tip The example templates include a template for this page. :::

#useBillingAddressForTax

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

#validateBusinessTaxIdAsVatId

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.

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

#Payments

#allowPartialPaymentOnCheckout

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

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>

::: tip 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

ISO codes for supported payment currencies.

See Payment Currencies.

#Units

#dimensionUnits

Unit type for dimension measurements.

Options:

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

#weightUnits

Units to be used for weight measurements.

Options:

• 'g'
• 'kg'
• 'lb'