Commit 6bb363f7e15 for woocommerce
commit 6bb363f7e1576103ad455a582f8e1e5f84971b19
Author: Brian Coords <bacoords@gmail.com>
Date: Thu Jul 23 07:12:55 2026 -0700
Clarify settings API usage documentation (#66894)
diff --git a/docs/extensions/settings-and-config/README.md b/docs/extensions/settings-and-config/README.md
index 95791e622be..069bd60eb00 100644
--- a/docs/extensions/settings-and-config/README.md
+++ b/docs/extensions/settings-and-config/README.md
@@ -16,7 +16,7 @@ The Settings API and admin pages section has six approaches, outlined in the tab
| Approach | Use when | Requires |
| :---- | :---- | :---- |
-| [Settings API](/docs/extensions/settings-and-config/settings-api/) | Adding settings fields to an existing WooCommerce page, such as a payment gateway or shipping method | PHP |
+| [Settings API](/docs/extensions/settings-and-config/settings-api/) | Defining settings for a configurable component, such as a payment gateway or shipping method | PHP |
| [Settings pages](/docs/extensions/settings-and-config/extend-wc-settings-page/) | Your extension needs a full tab under **WooCommerce > Settings** with one or more sections | PHP |
| [Settings tab sections](/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab/) | Your settings belong under an existing WooCommerce tab rather than a new page | PHP |
| [Admin pages](/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages/) | Your extension needs a standalone page outside WooCommerce's settings structure | PHP or JavaScript |
@@ -25,41 +25,9 @@ The Settings API and admin pages section has six approaches, outlined in the tab
## Settings API
-`WC_Settings_API` is the class that all WooCommerce settings build on, with payment gateways and shipping methods directly extending it. It's going to be the right tool when your extension adds settings fields to an existing WooCommerce context instead of creating a standalone settings page.
+`WC_Settings_API` provides field definition, rendering, loading, and saving for configurable WooCommerce components. Plugin developers usually inherit it through `WC_Payment_Gateway`, `WC_Shipping_Method`, or `WC_Integration` rather than extending it directly.
-There are three core responsibilities of this class:
-
-- Define fields in `init_form_fields()`.
-- Render them through `admin_options()`.
-- Hook `process_admin_options()` to the update hook that matches your context.
-
-For `process_admin_options()`, use the dynamic update hook for the context and append the gateway or shipping method ID. Payment gateways use `woocommerce_update_options_payment_gateways_{$gateway_id}`, while shipping methods use `woocommerce_update_options_shipping_{$shipping_method_id}`.
-
-The API lets you control field placements without presupposing a location. However, this means it doesn't create a settings page for you, so you'll need to register that separately if needed. For extensions that fit within payment or shipping contexts, you are extending the same class that WooCommerce's own gateways use.
-
-```php
-class My_Extension_Settings extends WC_Settings_API {
- public function __construct() {
- $this->id = 'my_extension';
- $this->init_form_fields();
- $this->init_settings();
- add_action(
- 'woocommerce_update_options_payment_gateways_' . $this->id,
- array( $this, 'process_admin_options' )
- );
- }
-
- public function init_form_fields() {
- $this->form_fields = array(
- 'enabled' => array(
- 'title' => __( 'Enable', 'my-extension' ),
- 'type' => 'checkbox',
- 'default' => 'yes',
- ),
- );
- }
-}
-```
+Use the [Payment Gateway API](/docs/features/payments/payment-gateway-api/), [Shipping Method API](/docs/features/shipping/shipping-method-api/), or [integration settings](/docs/extensions/settings-and-config/implementing-settings/) guide for a complete implementation.
## Settings pages
diff --git a/docs/extensions/settings-and-config/settings-api.md b/docs/extensions/settings-and-config/settings-api.md
index d381ff757d1..2cfec4a8ac2 100644
--- a/docs/extensions/settings-and-config/settings-api.md
+++ b/docs/extensions/settings-and-config/settings-api.md
@@ -86,18 +86,22 @@ This will output your settings in the correct format.
## Saving your settings
-To have your settings save, add your class's `process_admin_options` method to the appropriate `_update_options_` hook. The hook includes the gateway or shipping method ID. For example, payment gateways should use:
+`WC_Settings_API` does not create a settings screen or save action by itself. The integration that renders the settings must call `process_admin_options()` when its form is submitted.
+
+WooCommerce provides save actions for its registered settings integrations. A `WC_Payment_Gateway` subclass registered with WooCommerce should use the dynamic payment gateway action, which includes its gateway ID:
```php
add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
```
-Shipping methods use:
+A `WC_Shipping_Method` subclass registered with WooCommerce should use the dynamic shipping method action, which includes its method ID:
```php
add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );
```
+These actions are only fired for gateways or shipping methods registered with WooCommerce. If you extend `WC_Settings_API` directly, the code that renders your form must also provide its save handler.
+
## Loading your settings
In the constructor you can load the settings you previously defined: