Custom site and organization preferences for configuration values
Key Takeaway
A custom preference lives on SitePreferences, where values can differ for each site, or on OrganizationPreferences, where values are global. Read it from the matching entry point: Site.getCurrent() for site preferences and System.getPreferences() for global preferences.
Custom preferences are configuration values that a developer defines as custom attributes on the SitePreferences or OrganizationPreferences system objects. Merchants then set the values in Business Manager. Storefront code reads the values at runtime. As a result, features become configurable, so they can be adapted to changing requirements later.
Site and organization preferences
The two system objects differ in scope. SitePreferences holds site-specific values that can differ for each site. OrganizationPreferences holds global values that apply to all sites in the organization.
Neither object has system attributes. Each exists only as a place to define custom attributes. There is logically one SitePreferences instance per site. SitePreferences and OrganizationPreferences each allow at most 500 custom attribute definitions.
A retailer runs a US site and a UK site. The US site offers free returns for 30 days, but the UK site offers 14 days. A freeReturnDays preference goes on SitePreferences, so each site gets its own value. Both sites share one customer support email address, so a supportEmail preference goes on OrganizationPreferences. Its single value applies to all sites in the organization.