Settings
Every setting is editable in the control panel under Checkout. A site may also ship a config/foster-checkout.php file, which overrides the control panel.
Screens#
| Screen | Config key | Holds |
|---|---|---|
| Appearance | branding |
Brand color, header background, Google font family, logo path, component style, field label placement, title prefix |
| Features | options and addressLookup |
Checkout page layout format, the other enable* switches, and the Klaviyo list ID. Blank list ID hides the newsletter checkbox. Multi-page is the default |
| Line Items | lineItems and lineItemOptionRules |
Whether a line item shows its SKU and its stock count, whether its options are shown, which option names are hidden, how far option values are cut, and the rules that rewrite an option’s name and value |
| Products | products |
Per product type, the field holding the cart preview image. Blank falls back to the product’s own image |
| Gateways | paymentGateways |
Per gateway: the name customers see, a field layout, and extra payment form parameters |
| General | paths and the keys below |
Cart, checkout, account and cancel paths, plus the built-in cart template switch |
Other keys on the General screen:
| Setting | Config key | Holds |
|---|---|---|
| Head include, Body include | includes |
Template paths injected into every cart and checkout page. See custom includes |
| Priority countries | priorityCountries |
Country codes shown at the top of country dropdowns, in the order listed. See address fields |
| Hidden address fields | hiddenAddressFields |
Address fields left off the checkout. They stay in the control panel. A field the address layout marks required is always shown |
| Required address fields | requiredAddressFields |
Address fields required at the checkout beyond what the address layout asks for. A hidden field is never required |
| Show a third address line | showAddressLine3 |
Whether checkout address forms offer a third address line. Off by default |
| Let customers name a saved address | showAddressLabelField |
Whether the label of a saved address is editable at the checkout. It shows only when a customer edits an address they already saved |
| Zero value gateways | zeroValueGatewayHandles |
Gateways available when an order totals zero |
| Customer order notes field | customerOrderNotesFieldHandle |
Field on Orders holding the customer’s note. Blank hides the order notes form |
| Content translation method | contentTranslationMethod |
See below |
Defaults#
Every setting and its default, as the plugin ships.
| Setting | Config key | Default |
|---|---|---|
| Brand color | branding.color |
#1F2937 |
| Header background | branding.headerBgColor |
#F3F3F3 |
| Google font family | branding.font |
Rubik |
| Logo path | branding.logo |
empty |
| Component style | branding.style |
rounded |
| Field label placement | branding.labelStyle |
floating |
| Title prefix | branding.title |
empty |
| Favicon set | branding.faviconConfig |
empty |
| Checkout layout | options.enableSinglePageCheckout |
false |
| Save for later | options.enableSaveForLater |
false |
| Placeholder images | options.enablePlaceholderImages |
false |
| Page transitions | options.enablePageTransitions |
false |
| Verify shipping addresses | options.enableAddressVerification |
false |
| Shipping estimator | options.enableEstimatedShipping |
false |
| Klaviyo list ID | options.klaviyoListId |
none |
| Payment due date field | options.paymentDueDateFieldHandle |
none |
| Imager X transform | options.imagerXConfig |
none |
| Address suggestions | addressLookup.enabled |
false |
| Suggestion provider | addressLookup.provider |
google |
| Suggestion API key | addressLookup.apiKey |
none |
| Show line item SKU | lineItems.showLineItemSku |
true |
| Show line item stock count | lineItems.showLineItemStock |
true |
| Show line item options | lineItems.enableLineItemOptions |
true |
| Hidden option prefix | lineItems.hiddenLineItemOptionPrefix |
_ |
| Option value length limit | lineItems.lineItemOptionValueMaxLength |
none |
| Cart path | paths.cart |
cart |
| Use the built-in cart template | paths.useCartTemplate |
true |
| Checkout path | paths.checkout |
checkout |
| Cancel path | paths.cancel |
/ |
| Account path | paths.account |
/ |
| Head include | includes.head |
empty |
| Body include | includes.body |
empty |
| Newsletter checkbox label | options.subscribe |
none |
| Delivery date label, message, estimate, display | options.deliveryDate.label, .message, .estimate, .display |
none |
| Content translation method | contentTranslationMethod |
site |
| Customer order notes field | customerOrderNotesFieldHandle |
none |
| Priority countries | priorityCountries |
empty |
| Hidden address fields | hiddenAddressFields |
empty |
| Required address fields | requiredAddressFields |
empty |
| Show a third address line | showAddressLine3 |
false |
| Let customers name a saved address | showAddressLabelField |
false |
| Zero value gateways | zeroValueGatewayHandles |
empty |
| Line item option rules | lineItemOptionRules |
empty |
| Product image fields | products |
empty |
| Product image field | products.<handle>.productImageHandle |
none, so the product’s own image is used |
| Variant image field | products.<handle>.variantImageHandle |
none |
| Payment gateways | paymentGateways |
empty |
| Gateway name customers see | paymentGateways.<handle>.label |
empty, so the gateway’s own name is used |
| Gateway note | paymentGateways.<handle>.note |
empty |
| Gateway payment form params | paymentGateways.<handle>.params |
empty |
Some settings have no control panel field and are set in config/foster-checkout.php only: branding.faviconConfig, options.paymentDueDateFieldHandle, options.imagerXConfig, options.enableEstimatedShipping, options.deliveryDate.estimate and options.deliveryDate.display.
options.subscribe, paymentGateways.<handle>.note and the delivery date label and message are edited at Checkout -> Content. A config file may still set any of them, and a note or estimate written as a PHP closure can only live there. See content.
options.enableEstimatedShipping is unfinished.
What overrides what#
The config file is merged over stored settings on every request, so a key set in the file always wins. That field is shown disabled with a warning naming it, and a posted value for a pinned key is discarded server side.
This is being overridden by the
branding.colorsetting in theconfig/foster-checkout.phpfile.
The merge applies per key. Setting branding.color in the config file pins that one field and leaves the rest of the Appearance screen editable. Remove the key from the config file to hand the field back.
A list is pinned whole rather than merged. A config file setting priorityCountries replaces the stored list; it does not add to it. The same holds for hiddenAddressFields, requiredAddressFields and zeroValueGatewayHandles.
A gateway’s field layout is stored outside plugin settings, so it stays editable even where paymentGateways is set in the config file.
Address suggestions#
Suggestions come from Google Places or Loqate, chosen on the Features screen. Neither is included; the site supplies its own account and key.
Set the key to an environment variable name so it stays out of project config:
FC_ADDRESS_LOOKUP_KEY=your-key-hereThen set the control panel’s API key field to $FC_ADDRESS_LOOKUP_KEY, not the key itself.
Suggestions appear on the shipping address only, and are off until a provider and key are set.
Only one address tool runs at a time. Avalara address verification wins: while it is running, suggestions are skipped, because verification checks the address the customer settled on rather than one picked from a list.
Avalara covers the United States and Canada. It answers Country not supported for anywhere else, which the checkout treats as no suggestion, so a store shipping elsewhere gets nothing from verification and nothing to say why. Both suggestion providers work internationally, Loqate the more widely.
Test the connection on the Features screen runs one lookup and names the error, which is the only place a wrong key shows.
Both providers bill per lookup, and the endpoint that calls them is public. Cap the spend at the provider. In Google Cloud, set a daily and a per-minute quota on the Places API. Loqate sells prepaid credit, which caps itself. The plugin sets no rate limit of its own.
A failed lookup is never shown to the customer. A revoked key, an exhausted account or an unreachable provider returns no suggestions and writes the reason to the log.
Content translation method#
How checkout copy varies across sites, using Craft’s own field translation methods. On a single-site install all three behave identically.
| Value | Behavior |
|---|---|
none |
One copy shared by every site |
site |
A copy per site (default) |
language |
Sites speaking the same language share a copy |
Gateway field layouts#
A gateway’s fields are chosen with Craft’s field layout designer. The same rules apply as for checkout fields: only fields already on the order can be used, only some field types are supported, and a field’s placeholder and limits are set on the field itself. See checkout fields.
Settings that stay in config#
| Setting | Why |
|---|---|
A gateway note |
May be a PHP closure, which the control panel cannot represent. The plugin falls back to it whenever the stored copy for that gateway is empty |
options.deliveryDate.estimate, options.deliveryDate.display |
Accept a closure or a Twig string, because they compute a date and a visibility flag rather than holding copy |