{"slug":"wc-shipping-method","title":"wc-shipping-method","summary":"Build a zone-based WooCommerce shipping method with `WC_Shipping_Method`. Covers deferred class loading, registration, instance settings and modal support flags, package-based calculation, unique rate IDs, decimal/tax handling, availability, save behavior, caching, WooCommerce 11","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-16T14:52:18.262638Z","repo":{"url":"https://github.com/Lonsdale201/wp-agent-skills","stars":26,"forks":2,"license":"MIT","updatedAt":"2026-11-15T13:11:43Z"},"bodyHtml":"<hr>\n<h2>name: wc-shipping-method\ndescription: Build a zone-based WooCommerce shipping method with <code>WC_Shipping_Method</code>. Covers deferred class loading, registration, instance settings and modal support flags, package-based calculation, unique rate IDs, decimal/tax handling, availability, save behavior, caching, WooCommerce 11's private <code>product_shipping_class</code> taxonomy boundary, and testing. Use when adding carrier rates, shipping-class rules, custom shipping logic, a feature-only settings modal, or a method with no per-zone settings UI.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"woocommerce\"\nwp-skills-plugin-version-tested: \"11.0.0\"\nwp-skills-php-min: \"7.4\"\nwp-skills-last-updated: \"2026-08-05\"</h2>\n<h1>WooCommerce shipping method</h1>\n<p>WooCommerce calculates shipping per package. A method receives one package and adds zero or more rates for that package.</p>\n<h2>Load and register</h2>\n<p>With Composer PSR-4 autoloading, defer registration until WooCommerce has loaded its shipping base class:</p>\n<pre><code>add_action( 'woocommerce_shipping_init', static function (): void {\n    add_filter( 'woocommerce_shipping_methods', static function ( array $methods ): array {\n        $methods['myplugin_carrier'] = MyPlugin\\Shipping\\CarrierMethod::class;\n        return $methods;\n    } );\n} );\n</code></pre>\n<p>The array key must match the class <code>$id</code>. Register a class name; WooCommerce creates one object per zone-method instance.</p>\n<h2>Zone method scaffold</h2>\n<pre><code>namespace MyPlugin\\Shipping;\n\nuse Automattic\\WooCommerce\\Utilities\\NumberUtil;\n\nfinal class CarrierMethod extends \\WC_Shipping_Method {\n    protected $cost = '0';\n\n    public function __construct( $instance_id = 0 ) {\n        $this-&gt;id                 = 'myplugin_carrier';\n        $this-&gt;instance_id        = absint( $instance_id );\n        $this-&gt;method_title       = __( 'My Carrier', 'myplugin' );\n        $this-&gt;method_description = __( 'Calculated delivery by My Carrier.', 'myplugin' );\n        $this-&gt;supports           = array(\n            'shipping-zones',\n            'instance-settings',\n            'instance-settings-modal',\n        );\n\n        $this-&gt;init_form_fields();\n\n        // get_option() reads instance settings lazily for declared instance fields.\n        $this-&gt;title      = $this-&gt;get_option( 'title', __( 'My Carrier', 'myplugin' ) );\n        $this-&gt;tax_status = $this-&gt;get_option( 'tax_status', 'taxable' );\n        $this-&gt;cost       = $this-&gt;get_option( 'cost', '0' );\n    }\n\n    public function init_form_fields(): void {\n        $this-&gt;instance_form_fields = array(\n            'title' =&gt; array(\n                'title'       =&gt; __( 'Name', 'myplugin' ),\n                'type'        =&gt; 'text',\n                'default'     =&gt; __( 'My Carrier', 'myplugin' ),\n                'description' =&gt; __( 'Shown to customers at checkout.', 'myplugin' ),\n                'desc_tip'    =&gt; true,\n            ),\n            'cost' =&gt; array(\n                'title'             =&gt; __( 'Cost', 'myplugin' ),\n                'type'              =&gt; 'text',\n                'default'           =&gt; '0',\n                'sanitize_callback' =&gt; static function ( $value ): string {\n                    return NumberUtil::sanitize_cost_in_current_locale( $value );\n                },\n            ),\n            'tax_status' =&gt; array(\n                'title'   =&gt; __( 'Tax status', 'myplugin' ),\n                'type'    =&gt; 'select',\n                'default' =&gt; 'taxable',\n                'options' =&gt; array(\n                    'taxable' =&gt; __( 'Taxable', 'myplugin' ),\n                    'none'    =&gt; _x( 'None', 'Tax status', 'myplugin' ),\n                ),\n            ),\n        );\n    }\n\n    public function calculate_shipping( $package = array() ): void {\n        if ( empty( $package['destination']['country'] ) ) {\n            return;\n        }\n\n        $cost = wc_format_decimal( $this-&gt;cost );\n        if ( '' === $cost || (float) $cost &lt; 0 ) {\n            return;\n        }\n\n        $this-&gt;add_rate( array(\n            'id'      =&gt; $this-&gt;get_rate_id( 'standard' ),\n            'label'   =&gt; $this-&gt;title,\n            'cost'    =&gt; $cost,\n            'package' =&gt; $package,\n        ) );\n    }\n}\n</code></pre>\n<p>Declare extension-owned properties instead of relying on dynamic properties.</p>\n<h2>Settings model</h2>\n<p><code>instance_form_fields</code> fully controls the per-zone modal. WooCommerce does not inject a default title/cost field into custom methods.</p>\n<table>\n<thead>\n<tr>\n<th>Support flag</th>\n<th>Effect</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>shipping-zones</code></td>\n<td>Method can be added to zones</td>\n</tr>\n<tr>\n<td><code>instance-settings</code></td>\n<td>Method has per-instance settings</td>\n</tr>\n<tr>\n<td><code>instance-settings-modal</code></td>\n<td>Use the current Backbone modal UI</td>\n</tr>\n<tr>\n<td><code>settings</code></td>\n<td>Legacy/global non-instance settings page</td>\n</tr>\n</tbody>\n</table>\n<p>For no modal, use only:</p>\n<pre><code>$this-&gt;supports = array( 'shipping-zones' );\n</code></pre>\n<p>Do not hide unwanted fields with CSS/JavaScript or declare then unset them. Declare only the fields owned by the method.</p>\n<p><code>get_instance_option()</code> lazily calls <code>init_instance_settings()</code>. The base settings arrays already default to arrays; a method with no fields does not need <code>init_settings()</code> merely to avoid null notices.</p>\n<h2>Saving settings</h2>\n<p>The shipping-zone AJAX flow calls the selected instance's <code>process_admin_options()</code> directly. This validates the <code>instance_id</code>, reads only declared fields, applies sanitizers, and updates the instance option.</p>\n<p>The classic action wiring:</p>\n<pre><code>add_action(\n    'woocommerce_update_options_shipping_' . $this-&gt;id,\n    array( $this, 'process_admin_options' )\n);\n</code></pre>\n<p>is required for global/legacy settings. Built-in methods may register it for mixed compatibility, but a zone-only method does not depend on this action for modal saves.</p>\n<h2>Package contract</h2>\n<p>Use the supplied package, not global cart assumptions:</p>\n<pre><code>contents             cart lines in this package\ncontents_cost        package contents value\napplied_coupons      active coupon codes\nuser                 shopper data\ndestination          country/state/postcode/city/address\ncart_subtotal        package/cart subtotal context\n</code></pre>\n<p>A cart can be split into several packages. Calling <code>WC()-&gt;cart-&gt;get_cart()</code> inside calculation can price items that are not in the current package.</p>\n<p>External carrier calls must have short timeouts and deterministic fallbacks. Cache by a bounded hash of normalized destination, package dimensions/weight/value, service settings, and currency. Never include full addresses or customer PII in logs/cache keys.</p>\n<h2>Rate IDs and multiple services</h2>\n<p><code>get_rate_id()</code> returns method and instance components. If one method emits multiple rates, pass a stable service suffix:</p>\n<pre><code>$this-&gt;get_rate_id( 'standard' );\n$this-&gt;get_rate_id( 'express' );\n</code></pre>\n<p>Without suffixes, later rates can collide. Never use a translated label as an ID.</p>\n<h2>Costs and taxes</h2>\n<ul>\n<li>Store costs as sanitized decimal strings; do not use localized raw input in calculations.</li>\n<li>Leave <code>taxes</code> unset in <code>add_rate()</code> to let WooCommerce calculate shipping taxes from cost and tax status.</li>\n<li>Pass <code>taxes =&gt; false</code> only for an intentionally non-taxable rate.</li>\n<li>Do not manually add tax to cost unless the contract explicitly supplies tax-inclusive rates and you correctly handle <code>woocommerce_shipping_prices_include_tax</code>.</li>\n<li>Avoid negative shipping rates; use discounts/coupons for discounts.</li>\n</ul>\n<h2>Availability</h2>\n<p>Return no rates when requirements are not met. If overriding <code>is_available()</code>, retain parent/zone enablement behavior and evaluate only package-relevant rules. Sanitize destination data before sending it to a carrier.</p>\n<h2>Shipping-class taxonomy visibility in WooCommerce 11.0</h2>\n<p>WooCommerce 11.0 registers <code>product_shipping_class</code> with <code>public =&gt; false</code>, <code>rewrite =&gt; false</code>, and no frontend query variable. Product/variation assignment, <code>WC_Product::get_shipping_class_id()</code>, rate calculations, and admin management continue to work; the change removes shipping-class public archives and public taxonomy discovery.</p>\n<p>Use product CRUD and term APIs for shipping logic. Do not build customer-facing URLs, sitemap entries, or frontend queries that depend on <code>product_shipping_class</code> being public. If a site-specific integration deliberately needs the old visibility, it can alter registration through <code>woocommerce_taxonomy_args_product_shipping_class</code> or WordPress's <code>register_product_shipping_class_taxonomy_args</code>, but test rewrite/query exposure and information disclosure explicitly. For a new public classification feature, prefer a separate extension-owned taxonomy rather than repurposing shipping configuration as storefront content.</p>\n<h2>Testing</h2>\n<p>Test:</p>\n<ol>\n<li>Add/remove method in several zones and save separate instance settings.</li>\n<li>Guest and logged-in addresses, incomplete postcode, no-shipping destinations.</li>\n<li>Multiple packages and multiple services from one instance.</li>\n<li>Taxable/non-taxable stores, decimal separators, zero cost, coupons.</li>\n<li>Carrier timeout/error, cache hit/miss, duplicate recalculation in one request.</li>\n<li>Classic and Store API/Checkout Block rate display.</li>\n</ol>\n<h2>Critical rules</h2>\n<ul>\n<li>Register/load after <code>woocommerce_shipping_init</code>.</li>\n<li>Price the supplied package only.</li>\n<li>Give every emitted service a stable unique rate suffix.</li>\n<li>Sanitize settings and decimal values at the boundary.</li>\n<li>Do not perform unbounded carrier calls on every recalculation.</li>\n<li>Do not rely on a settings action for per-zone AJAX persistence.</li>\n<li>Do not use <code>product_shipping_class</code> as a public archive or sitemap taxonomy in WooCommerce 11.0.</li>\n</ul>\n<h2>References</h2>\n<ul>\n<li>Base settings/rate contract: <code>includes/abstracts/abstract-wc-shipping-method.php</code>.</li>\n<li>Zone method examples: <code>includes/shipping/free-shipping</code> and <code>includes/shipping/flat-rate</code>.</li>\n<li>Official documentation: <a href=\"https://woocommerce.com/document/shipping-method-api/\">https://woocommerce.com/document/shipping-method-api/</a></li>\n<li>Verified source paths:\n<ul>\n<li><code>wp-content/plugins/woocommerce/includes/abstracts/abstract-wc-settings-api.php</code></li>\n<li><code>wp-content/plugins/woocommerce/includes/class-wc-shipping.php</code></li>\n<li><code>wp-content/plugins/woocommerce/includes/shipping/free-shipping/class-wc-shipping-free-shipping.php</code></li>\n<li><code>wp-content/plugins/woocommerce/includes/shipping/flat-rate/class-wc-shipping-flat-rate.php</code></li>\n</ul>\n</li>\n</ul>\n","files":[{"path":"SKILL.md","sizeBytes":10125,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-16T14:58:19.922279Z","sha256":"92D0DB0F8FFF13D8ED265CEFB19BC9D20DA02C3FB3A7C63F49BC86A8A91E5E37","sizeBytes":3896},"review":null,"source":{"repositoryUrl":"https://github.com/Lonsdale201/wp-agent-skills","path":"woocommerce/wc-shipping-method","license":"MIT","commit":"9025fda280d15da3e2ba376a66940e75bd45f3ce","subtreeSha":"9DD27312AA122F998C8F294C1757B9A9E720240F2D7C0462169F40EF0C183C57","lastSyncedAt":"2026-11-17T00:39:45.243627Z"},"reviewedAt":"2026-09-16T15:18:28.391541Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/woocommerce/wc-shipping-method"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart"},{"target":"git","command":"git clone https://github.com/Lonsdale201/wp-agent-skills.git"}]}