Settings and Admin Pages

The fields are the form_fields array, usually built in init_form_fields(). The array key is the field key; it becomes part of the HTML field name and the key of the stored array. The default values and the extra keys that WooCommerce understands are:

The built-in types are text, safe_text (added in 7.6.0, mostly used for gateway-related settings), price, decimal, password, color, textarea, checkbox, select, multiselect and title. Each has a generate_<type>_html() method that prints the table row and a validate_<type>_field() method that cleans the posted value. A title field prints a heading and stores nothing. A checkbox is stored as yes or no; price and decimal run the value through wc_format_decimal(); password is trimmed but otherwise untouched so that special characters survive.

init_settings() reads the option woocommerce_<id>_settings (the base class joins plugin_id, which is woocommerce_, the object’s id and the suffix _settings; get_option_key() returns it) and falls back to the field defaults while the option does not exist. get_option( $key ) returns one value, with the default when the key is missing. Saving is process_admin_options(): for every field except titles it calls get_field_value(), which resolves the cleaner in this order, and then stores the whole array in one update_option() call:

The whole array passes through the filter woocommerce_settings_api_sanitized_fields_{id} just before it is written, which is the place for a rule that involves several fields. An exception thrown by a validate method is caught by process_admin_options() and stored in the object’s errors list; the field keeps the value it had before.

The example is the roaster integration of the Pocket Coffee shop: a base URL, an API token and a debug switch. The class is registered with the woocommerce_integrations filter in the main plugin file (shown later) and appears under WooCommerce > Settings > Integration.

Source: WooCommerce docs: Creating custom settings for WooCommerce integrations

Source: WooCommerce docs: Settings API

Saving the form with an endpoint that ends in a slash, a debug box ticked and first a 70-character token and then a short one gave this on 11.2.1. The long token was refused with a red notice and the stored token stayed as it was; the short one was stored in clear text, because a password field only hides the characters in the browser:

Three details are worth knowing. First, the trailing slash of the endpoint was removed by the woocommerce_settings_api_sanitized_fields_{id} filter, after the field validators ran. Second, the first version of validate_api_token_field() threw an Exception instead of calling WC_Admin_Settings::add_error(): the field was left unchanged, the page still said Your settings have been saved and no error appeared, because the integration screen does not print the object’s errors list. WC_Admin_Settings::add_error() queues a notice that the settings screen does print. Third, an option stored in plain text is readable by every plugin and by anyone with a database dump; for a real secret keep the value in a constant in wp-config.php or an environment variable, and let the field only show whether it is set.

A field with an unknown type is drawn by a method called generate_<type>_html( $key, $data ) on the object, when one exists, or else by whatever is attached to the filter woocommerce_generate_{type}_html (added in 6.5.0), which receives an empty string, the key, the field array and the settings object and returns the markup of one table row. The posted value is cleaned by validate_<type>_field() or by the text fallback. WC_Settings_API also offers helpers for the markup (get_tooltip_html(), get_description_html(), get_custom_attribute_html()) that the built-in renderers use.

WC_Settings_Page registers its hooks in the constructor, and every hook name contains the page id, so the subclass must set $this->id and $this->label before it calls parent::__construct():

The tab is available at wp-admin/admin.php?page=wc-settings&tab=<id>, and a named section at &section=<section id>. On the lab store the Pocket Coffee tab appeared between Point of Sale and Advanced: the settings screen moves the tab with the id advanced to the end of the tab bar, so an extension tab never comes after it. The page class of the lab is loaded lazily, from the filter callback, because WC_Settings_Page only exists once WooCommerce has included it.

A page has one section by default: the empty string. Override get_own_sections() to return an array of section id => label; the empty key is the default section and should always be there. The links are only drawn when there is more than one section. The id goes into the URL through sanitize_title(), so keep it lowercase. The fields of a section come from, in this order:

The older get_settings() still exists and WooCommerce still calls it internally for the sake of legacy classes, but it is deprecated since 5.4.0: do not override it in new code. Whatever the method returns passes through the filter woocommerce_get_settings_{id}, which receives the settings array and the section id, so other plugins can add or remove fields. The section list passes through woocommerce_get_sections_{id}.

WC_Admin_Settings::output_fields() draws a settings array and WC_Admin_Settings::save_fields() saves it. The array is a list of field arrays, which are close to the WC_Settings_API ones but not identical:

The types WooCommerce draws itself are title, sectionend, info (read-only text in text), notice (notice_type and text), text, password, number, email, url, tel, color, date, datetime, datetime-local, month, time, week, textarea, select, multiselect, radio, checkbox, single_select_page, single_select_page_with_search, single_select_country, multi_select_countries, relative_date_selector, image_width (kept for old code) and slotfill_placeholder. They are also available as constants (WC_Settings_Page::TYPE_TEXT, WC_Settings_Page::TYPE_SELECT and so on). Any other type is passed to do_action( 'woocommerce_admin_field_' . $type, $field ), which is where a custom renderer attaches. A title field also fires woocommerce_settings_{id} right after it opens the table, and a sectionend fires woocommerce_settings_{id}_end and woocommerce_settings_{id}_after, which makes them anchors for extra rows or notes. Group the fields of one section between a title and a matching sectionend with the same id.

The tab has two sections. General holds the badge options (show it, label, freshness window, display mode) and a read-only preview drawn by a custom field type; Coffee Club holds the discount, the free-shipping threshold and the member roles. The class overrides get_settings_for_default_section() and get_settings_for_club_section(), attaches two option-specific sanitizers and an action that runs after the club section is saved.

Source: WooCommerce docs: How to add a settings page

The main plugin file loads the class from the registration callback and registers the other pieces of the example. It also declares HPOS compatibility, as every extension does (see HPOS): a settings plugin never touches orders, but an undeclared plugin makes WooCommerce show a compatibility warning.

Source: WooCommerce docs: Settings APIs and admin pages

The final block of that file, the filter on woocommerce_admin_features, is a test switch for the experimental settings UI that a later section explains; it only acts on requests that carry the query argument pc_settings_ui, and it is not part of a normal extension.

When the merchant presses Save changes, WC_Admin_Settings::save() checks that the user has the manage_woocommerce capability (otherwise it ends the request with a 403) and the nonce of the form (check_admin_referer( 'woocommerce-settings' )), fires the save hooks, queues the success notice and queues a rewrite-rule flush. For a WC_Settings_Page the page’s save() method calls WC_Admin_Settings::save_fields() on the fields of the current section. save_fields() handles each field by type: checkboxes become yes or no, textareas pass through wp_kses_post(), multiselects are cleaned item by item, a select is forced to one of the keys of its options (or the default), a password is only trimmed, and everything else goes through wc_clean(). Then two filters run, in this order, and the second can overrule the first:

A filter that returns null skips the option: nothing is written and the stored value stays. The values are written with update_option(), with the autoload flag of the field. A trace of the save hooks on the lab store, recorded by a small development aid in the plugin that appends each hook name to an option, gave this order for the default section followed by the Coffee Club section:

The default section does not fire a section-specific hook because its section id is empty, so code that must run on every save of the tab belongs on woocommerce_update_options_{id}; code for one section belongs on woocommerce_update_options_{id}_{section} (the class attaches after_club_saved() there). woocommerce_update_options fires for every settings tab and woocommerce_settings_saved is the last hook of the save.

The sanitizers did their work. Posting 900 as the freshness window stored 365; posting 45,50 as the free-shipping threshold stored 4550 and not 45.50, because wc_format_decimal() treats the comma as a thousands separator when the shop’s decimal separator is a dot. The first rule is a reason to add a sanitizer; the second is a reason to test with the locale of the shop:

A settings tab saves one option per field, so the values read back with get_option( 'pocket_coffee_freshness_days' ). Use WC_Admin_Settings::get_option( 'pocket_coffee_freshness_days', '30' ) when the field has a default and the option may not exist yet; it also understands array-style option names (my_option[key]). Compare with yes and no for checkboxes.

Every WC_Settings_Page is exposed to the settings REST API without any extra code. WC_Register_WP_Admin_Settings hooks the page into woocommerce_settings_groups and woocommerce_settings-{id} and lists the fields of all its sections, so the group pocket_coffee exists next to general, products and the others:

The same data is reachable at /wc/v3/settings/pocket_coffee (with a consumer key and secret) and at the wc-analytics route that the React admin uses. A write through the REST API goes through WC_Admin_Settings::save_fields() as well, so the sanitizers apply: a PUT of 900 to pocket_coffee_freshness_days answered with 900 and left 365 in the database. The response echoes the request; the stored value is what the filters returned, so read the option back when the exact value matters.

The title and sectionend rows are not listed, and neither is the preview row (a custom type with is_option set to false). The products and shipping groups also list the fields of the sections that the example adds to those tabs.

woocommerce_get_sections_{tab} adds the section link; woocommerce_get_settings_{tab} returns the fields when the current section is yours and returns the received array otherwise. The tab ids are the page ids: general, products, tax, shipping, checkout (the Payments tab), account, email, integration, site-visibility, point-of-sale and advanced. The example adds a Roast badge section to Products:

Source: WooCommerce docs: How to add a section to a settings tab

The section appears at wc-settings&tab=products&section=pocket_coffee_badge, saves with the Products tab’s own save(), and its unticked checkbox was stored as no:

Because the hook receives the whole page’s settings, the callback must return $settings unchanged for every other section: returning only your own fields on every call would replace the core fields of the Products tab.

Since 10.9.0 a section can be an object. SettingsSectionInterface has six methods: get_parent_page_id() (the tab id), get_id(), get_label(), get_settings( WC_Settings_Page $parent_page ) (the same field arrays as above), get_script_handles() (scripts to load before the experimental settings UI mounts) and get_save_adapter() (form_post or none). The abstract class Automattic\WooCommerce\Admin\Settings\SettingsSection implements the last two with defaults, so an extension only writes the first four methods. The object is registered on the action woocommerce_settings_sections_registration, which receives the SettingsSectionRegistry. The registry fires that action lazily, the first time any code asks for a registered section, and logs a failure inside a registration callback instead of letting it break the page.

Source: WooCommerce docs: How to add a settings page, adding a section to an existing settings page

SettingsSectionRegistry::register() returns false and calls wc_doing_it_wrong() when the parent page id or the section id is empty, when a section with the same ids is already registered, and, on the checkout tab, when the id equals the id or the class name of an installed payment gateway (those ids are the gateways' own sections). The ids go through sanitize_title(). The section above appeared at wc-settings&tab=shipping&section=pocket_coffee_parcels, accepted 5.5 and saved it in the option pocket_coffee_max_parcel_kg; the shipping REST group listed the field.

wc_admin_connect_page( $options ) tells the controller that a screen WordPress already renders belongs to WooCommerce Admin. The options are id (required: the name of the page in the controller), screen_id (required for a connected page: what PageController::get_current_screen_id() returns on that screen), title (a string, or an array of breadcrumb pieces of which only the first links to path), path (the page’s address), parent (the id of a parent page, for breadcrumbs), and the optional capability, icon, position and js_page. Connected pages get the WooCommerce Admin header; the page itself is drawn by the callback you passed to WordPress.

The screen id is built from the WordPress screen id, the action and, for the pages in a list of pages with tabs (wc-reports, wc-settings, wc-status, wc-addons), the current tab, and for a few tabs also the section. A submenu page under the WooCommerce menu with the slug pocket-coffee-roast-log therefore has the screen id woocommerce_page_pocket-coffee-roast-log, the value used above. Three filters adjust the computation. The names in the public documentation (wc_admin_pages_with_tabs, wc_admin_page_tab_sections, wc_admin_current_screen_id) are not the ones in the 11.2.1 source, which are woocommerce_navigation_pages_with_tabs, woocommerce_navigation_page_tab_sections and woocommerce_navigation_current_screen_id; use the latter, and check the version you target. woocommerce_navigation_connect_page_options filters the options of every connected or registered page, and woocommerce_navigation_get_breadcrumbs, woocommerce_navigation_is_connected_page and woocommerce_navigation_is_registered_page change the breadcrumbs and the detection.

When the lab opened the Roast log page, WordPress printed the callback’s output under the WooCommerce Admin header titled Roast log, and the submenu entry was highlighted under WooCommerce.

wc_admin_register_page( $options ) takes the same options and adds the defaults parent null, capability view_woocommerce_reports, js_page true and path empty. The path is relative to the application: a value that does not start with wc-admin is turned into wc-admin&path=<path>, which WordPress shows as the menu link admin.php?page=wc-admin&path=<path>. With parent set to the id of an existing page (woocommerce is the top-level WooCommerce menu), the function calls add_submenu_page(); with parent null it calls add_menu_page() and the icon (a Dashicons class or a base64 SVG) and position options apply. The user needs the capability for the menu entry to show and the page to open. The public documentation says the default capability is manage_options; the source of 11.2.1 says view_woocommerce_reports, which shop managers have and administrators too. Pass capability explicitly, as the example does with manage_woocommerce.

Registration only creates the route and the menu entry. The page content comes from a JavaScript filter in your bundle:

Source: WooCommerce docs: Registering a React-powered page

container is a React component, path must equal the PHP path, breadcrumbs is an array of strings or elements, and navArgs is the identifier the scaffold adds. An address that the application has no entry for showed Sorry, you are not allowed to access this page inside the WooCommerce Admin frame on the lab store (path=/does-not-exist), and a JavaScript entry without a PHP registration has no menu entry, no breadcrumb parent and no capability of its own, so register both halves together.

One helper deserves a warning: wc_admin_url( $path, $query ) builds the &path= form only when $query is a non-empty array. Called as wc_admin_url( '/pocket-coffee' ) on the lab store it returned admin.php?page=wc-admin/pocket-coffee, an address that does not exist, while wc_admin_url( '/analytics/orders', array( 'period' => 'last_week' ) ) returned the right admin.php?page=wc-admin&path=/analytics/orders&period=last_week. For a page without a query use admin_url( 'admin.php?page=wc-admin&path=/pocket-coffee' ).

The home screen has a third, much smaller, extension point for navigation: the JavaScript filter woocommerce_admin_homescreen_quicklinks adds a link (title, href, icon) to the Extensions category of the store management links. The links must point to pages inside WooCommerce; external addresses are not supported. It improves discoverability, not configuration, and was not run.

Source: WooCommerce docs: Adding store management links

The versions checked on 2026-10-27 were Node.js 24.21.0 and npm 11.19.0 on the build machine, @wordpress/scripts 37.0.0, @woocommerce/dependency-extraction-webpack-plugin 5.1.0 and React 18.3 (the range that @woocommerce/components 14.1.0 supports; the scaffold pins react and react-dom to 18.3.x for that reason). The scaffold @woocommerce/create-woo-extension 2.1.0 generates exactly this setup; it requires Node.js 24.15 or later.

Source: WooCommerce docs: Building your first extension

The scaffold has a default variant (a React page with a few @woocommerce/components examples, an Admin/Setup class that registers the page and enqueues the bundle, tests, a .wp-env.json and a Composer package) and five others: add-report, add-task, dashboard-section, sql-modification and table-column, which extend Analytics, the task list and the home screen. The lab did not run the generator; it wrote the equivalent files by hand so that the page and the PHP stay small, and checked the scaffold’s template files in the 2.1.0 package (its Setup class enqueues the bundle in the same way as the listing below).

The two files that make the build WooCommerce-aware are the package.json and the webpack configuration. The configuration replaces the default DependencyExtractionWebpackPlugin of @wordpress/scripts with the WooCommerce subclass:

Source: WooCommerce repository: create-woo-extension

Source: WooCommerce repository: dependency extraction plugin

npm install added 1263 packages and npm run build finished in about a tenth of a second. The output, in build/, is the script and a PHP file that lists what the script needs:

Source: WordPress developer resources: dependency extraction plugin

The bundle is 2.6 KiB because WooCommerce, React and the WordPress packages are not in it. The asset file is what the plugin reads when it enqueues the script: WordPress then loads wc-components, wc-store-data and the rest first, in dependency order, and uses version (a hash of the content) as the cache buster.

The plugin maps every @woocommerce/<name> package that is listed in its packages.js to a script handle and a global. The rule is mechanical: the handle is wc-<name> and the global is wc.<camelCaseName>, with a few irregular cases that the table shows. The handles below were all present on the page of the lab (wc-components, wc-store-data, wc-navigation, wc-settings, wc-number, wc-currency, wc-date, wc-csv, wc-experimental, wc-notices, wc-sanitize and wc-tracks); the blocks packages follow the same rule in the plugin’s source.

The list of packages in version 5.1.0 of the plugin has no @woocommerce/product-editor: the product block editor was removed in 11.0.0, and its package went with it (see Products and Product Types). The bundledPackages option of the plugin keeps a package in the bundle instead of externalizing it. The @wordpress/* packages follow WordPress’s own rules (wp-element, wp-data, wp-components, wp-i18n and so on, plus react-jsx-runtime for the automatic JSX transform).

On the running page the globals were: wc.adminLayout, wc.app, wc.commandPalette, wc.components, wc.csvExport, wc.currency, wc.customerEffortScore, wc.data, wc.date, wc.experimental, wc.explat, wc.navigation, wc.notices, wc.number, wc.remoteLogging, wc.sanitize, wc.tracks, wc.wcEntities, wc.wcSettings and wc.wcTypes, and window.wcSettings held, among others, adminUrl, countries, currency, currentUserId, homeUrl, locale, orderStatuses, siteTitle, storePages, wcVersion, wpVersion and an admin object with preloadOptions, preloadSettings, currentUserData, manageStock, notifyLowStockAmount and shopUrl. The @woocommerce/settings helper getSetting( 'name', fallback ) reads that object.

The scaffold’s Setup class and the admin-pages.php file above enqueue the bundle on admin_enqueue_scripts, but only on WooCommerce Admin pages: PageController::is_admin_or_embed_page() is true on the wc-admin application and on connected (embedded) pages, so the script does not load on every wp-admin screen. The function exists in WooCommerce 11.2.1 and the scaffold guards the call with method_exists(), which is worth copying when the extension supports older releases. A script that is registered but whose dependency list contains an unknown handle never runs; a missing index.asset.php (the listing returns before enqueueing) means the page is empty with no error, which is why the listing checks file_exists().

The container below is the whole of src/index.js. It has two parts. BadgeSettings is a form for the two main badge options, backed by the settings group of the PHP tab; ProductsTable lists products in a TableCard, with paging driven by the URL.

Source: WooCommerce docs: Building your first extension

Opened at wp-admin/admin.php?page=wc-admin&path=/pocket-coffee in a headless Chromium, the page showed the WooCommerce Admin header with Pocket Coffee, the store activity panel, a Roast badge card with the toggle on and the freshness window at 30, and a Products table with the columns Product, SKU, Price and Stock and the paging footer, with no console errors. Changing the number to 21 and pressing Save sent one request, POST /wp-json/wc-analytics/settings/pocket_coffee/batch, with the whole group in update, and the option changed. The Price column shows the price field of each product as the REST API returns it, with two decimals; the first version of the page used formatValue() from @woocommerce/number for it and printed an empty cell, because that helper needs the full number configuration (separators and precision) rather than a bare precision.

Three lessons came out of building it. The useSettings() hook threw on first render (see the section on the data package); the number helper needs its whole configuration; and the table shows every product, because the example does not filter by status or type: a real report passes status, type or category in the arguments of getProducts().