Shipping Methods

WooCommerce > Settings > General decides where the store ships. The option woocommerce_ship_to_countries has four meanings: the empty value ships to all the countries the shop sells to, all ships to all countries, specific ships only to the countries chosen in woocommerce_specific_ship_to_countries, and disabled turns shipping and shipping calculations off (every product then behaves as if it did not need shipping). The selling countries are woocommerce_allowed_countries. These options limit the addresses the checkout accepts; the zones decide the costs.

WooCommerce > Settings > Shipping has the sections Shipping zones, Settings (the options below), Classes and Local pickup (the pickup locations of the block method). In 11.2.1 it also has Fulfillment providers when the fulfillments feature is on (see Fulfillments).

Source: WooCommerce docs: Shipping

Saving anything under the Shipping tab increments the shipping transient version (WC_Cache_Helper::get_transient_version( 'shipping', true )), which invalidates the cached zone and rate data.

A zone has a name, an order number and a list of regions: continents, countries, states (ES:B is Barcelona province) and postcodes. To find the zone of a package, WC_Shipping_Zones::get_zone_matching_package() builds a key from the country, state and normalized postcode of $package['destination'], looks for a cached answer in the shipping_zones object-cache group and otherwise asks the data store, which selects the zone with the lowest zone_order (and the lowest zone_id among equal orders) whose regions contain the destination. The rules of the query in 11.2.1:

Zone order is therefore the way to make a specific zone win over a general one: Berlin postcodes above Germany above Europe. Since 11.1.0 the zones screen shows a warning on a zone that can never be matched because a higher zone already covers all of its regions (WC_Shipping_Zones::get_zones_with_order_conflict_warnings(), whose message tells the merchant to move the zone above the one that shadows it).

Source: WooCommerce documentation: Setting up shipping zones

In the admin the zones screen has Add zone, a region picker and Add shipping method. The same data can be written four ways. Through WP-CLI the zone and its methods can be created and listed (the CLI has no command to set the regions of a zone; wp wc shipping_zone_location only lists them):

Source: WooCommerce docs: WC-CLI overview

The REST API writes regions with PUT /wc/v3/shipping/zones/{id}/locations, a list of { "code": ..., "type": ... } objects that replaces the zone’s locations. This is the script that created the Pocket Coffee test zones (the keys are placeholders; Basic authentication works over HTTPS only):

Source: WooCommerce REST API documentation

The same objects can be created in PHP, which is how a plugin or a migration ships a store’s zones. WC_Shipping_Zone::add_shipping_method() returns the new instance ID, and the instance settings are the option named by get_instance_option_key(). This script was run with wp eval-file; it created a zone, a flat-rate instance and a location, asked WooCommerce which zone matches an address in Rome, and deleted the zone:

Source: WooCommerce code reference: WC_Shipping_Zone

The other methods of WC_Shipping_Zone are get_zone_name(), get_zone_order(), get_zone_locations(), get_formatted_location(), get_shipping_methods( $enabled_only, $context ), set_locations(), clear_locations() and delete_shipping_method( $instance_id ); the static WC_Shipping_Zones adds get_zones(), get_zone( $id ), get_zone_by(), get_shipping_method( $instance_id ) and delete_zone(). Hooks fire when an instance is added (woocommerce_shipping_zone_method_added), deleted (woocommerce_shipping_zone_method_deleted) or switched on or off through REST (woocommerce_shipping_zone_method_status_toggled); woocommerce_shipping_zone_shipping_methods filters the methods a zone returns.

A zone with the country DE and the postcode range 10000...14199, order 19 (above the EU zone of order 21), with a flat rate of 5.00 EUR "Berlin courier", was created and three carts were priced through the Store API:

The location rows stored for that zone were DE country and 10000...14199 postcode. (Store API amounts are in minor units: 500 is 5.00 EUR.)

flat_rate charges a cost that can be a number or a formula. The instance settings are title, tax_status (taxable or none), cost, one class_cost_<term id> per shipping class, no_class_cost and type (class or order). Formulas may use the placeholders [qty] (the number of items that need shipping), [cost] (the total of their lines) and the shortcode [fee percent="10" min_fee="20" max_fee=""], which adds a percentage of [cost] bounded by a minimum and a maximum; arithmetic uses + - * / and parentheses and is evaluated by WC_Eval_Math, not by eval(). The filter woocommerce_evaluate_shipping_cost_args can change the arguments (qty, cost) before evaluation. Examples of valid costs: 10.00, 5.00 * [qty], 4.90 + [fee percent="3" min_fee="1"].

Shipping classes. A class (Settings > Shipping > Classes) groups products such as "Equipment". A product gets a class on its Shipping tab or through the REST field shipping_class (the slug). With classes defined, the flat rate adds the class costs: with type = class ("per class") it charges the base cost plus the cost of each class found in the package, and with type = order ("per order") it charges the base cost plus the highest class cost. An empty class cost means "no extra charge for this class"; no_class_cost is the extra charge for products with no class. WooCommerce stores class costs under the term ID since 2.5.0 (older settings used the slug). The test store had the class equipment-pcship (term 26) with the flat rate above (cost 9.90, class cost 14.90, per class); a cart with the Starter kit (class equipment-pcship) to Berlin returned flat_rate:5 at 24.80 EUR (9.90 + 14.90) and a cart with one 250 g bag returned 9.90.

Source: WooCommerce documentation: Flat rate shipping

free_shipping is a method with no cost whose availability depends on a requirement. requires is one of the empty value (no requirement), coupon (a valid coupon with "Allow free shipping" on), min_amount, either (minimum amount or coupon) and both. min_amount is compared with the cart’s displayed subtotal minus the coupon discounts (and minus the discount tax when prices are shown including tax) unless ignore_discounts is yes, in which case the order total before coupons is used. The comparison uses wc_get_price_decimals() rounding. Because it is only a method with is_available() logic, a free-shipping rate appears next to the paid ones; the preselected rate is the first one of the package in the classic cart and the first one that is not a local pickup method in the Cart and Checkout blocks (filter woocommerce_shipping_chosen_method), so a merchant who wants free shipping to replace the paid rate sets woocommerce_shipping_hide_rates_when_free (all other rates except local pickup are removed) or orders the instances so that the free one comes first. In the test the EU zone’s free shipping with a 60 EUR minimum appeared for three Starter kits (72 EUR) beside the flat rate, which stayed selected.

Source: WooCommerce documentation: Free shipping

There are two local pickup methods in 11.2.1 and they differ in important ways.

Both are local pickup methods: the order’s shipping address is hidden for them (woocommerce_order_hide_shipping_address), the checkout block does not require a shipping address when only pickup is chosen, and the filter woocommerce_local_pickup_methods lists the method IDs treated that way (the block method registers itself there). LocalPickupUtils::is_local_pickup_method() answers the question for any method ID, and WC_Shipping::calculate_shipping_for_package() still returns pickup rates for a package that cannot be shipped (for example to an unsupported country).

The classic instance was run as "Collect at the roastery" (cost 0) in the Portugal zone: it appeared next to the parcel rate, selecting it through the Store API changed total_shipping from 490 to 0, and an order placed with it stored the shipping line local_pickup, instance 4, total 0.00. The block method was run by writing the two options below (and restored to empty arrays right after the run, because it adds a rate to every package of the shared store):

Source: WooCommerce documentation: Local pickup

A cart to Berlin then listed a second rate:

Saving either option flushes the shipping transient version (flush_cache), so the change is visible at once. The settings and locations can also be written through the REST route registered by PickupLocationsRestController (capability manage_woocommerce), which is what the React screen uses.

A shipping method is a class that extends WC_Shipping_Method (which extends WC_Settings_API). WooCommerce keeps one prototype object per registered method (instance ID 0, used to list the method in the admin and to hold the global settings) and creates one object per instance in a zone with the instance ID passed to the constructor.

Source: WooCommerce docs: Shipping method API

$this->supports controls where the method appears in the admin:

The registration has two parts. The class is loaded on woocommerce_shipping_init (WC_Shipping::init() fires it, so the base class exists), and its name is added to the array of the filter woocommerce_shipping_methods, keyed by the method ID. woocommerce_load_shipping_methods fires after the registered classes are loaded for a package, with the package as argument, so a method can register an object manually (the block pickup method does). The WC_Shipping object keeps the registered methods; WC()->shipping()->get_shipping_classes() lists the shipping classes.

The rate ID is the key of everything the shopper and the order see. Never change the ID of a method that is in use: carts and orders store it.

Instance fields are defined in $this->instance_form_fields, usually in the constructor or an init() method, and saved with process_admin_options() which is hooked to woocommerce_update_options_shipping_<id>. Use sanitize_callback to validate each field when it is saved; a price field must be a text field (so that the decimal separator of the locale can be typed) with a callback that turns the locale’s separator into a dot. WooCommerce 11.2.1 offers NumberUtil::sanitize_cost_in_current_locale() for that, which the bundled methods use. The older documentation example writes its own sanitize_cost() that strips the currency symbol and throws an exception for non-numeric input.

The plugin file declares compatibility (as the payment plugin of the previous page does), loads the method class on woocommerce_shipping_init, adds it to woocommerce_shipping_methods and registers the parcel splitter on woocommerce_cart_shipping_packages.

Source: WooCommerce docs: Shipping method API

pocketcoffee_parcel has four instance settings: cost (the price of one parcel, default 4.90), free_over (the cart subtotal from which parcels are free, 0 disables the rule), max_weight (kilograms per parcel, default 5) and the usual title and tax_status. It is unavailable when the package is heavier than max_weight, which is how a zone can offer "no parcel service" for a single unit that is too heavy. The weight of each product is converted from the store’s unit with wc_get_weight( $weight, 'kg' ): the test store was installed with pounds (woocommerce_weight_unit = lbs) while the Pocket Coffee weights are kilograms, so the test products were saved with 0.5511 lb for the 250 g bag, 2.2046 lb for the 1 kg bag and 2.6455 lb for the kit. A plugin that reads $product->get_weight() without converting is wrong on every store whose unit differs from the one it assumed. The free-shipping rule compares $package['cart_subtotal'], the subtotal of the whole cart, which a package copy inherits, so a split cart still earns free shipping on its total.

Source: WooCommerce docs: Shipping method API

woocommerce_cart_shipping_packages receives the array of packages that the cart built (normally one). A plugin may return several: every package gets its own zone lookup, its own methods, its own rates and its own selection by the shopper (the Store API returns one entry per package, named Shipment 1 and Shipment 2 in the run below, and the Checkout block offers one choice of rates for each). WooCommerce adds package_id and package_name to each package after the filter ("Shipment" for one package, "Shipment 1" and "Shipment 2" for two, as printed below), so a filter must not set them. The function below fills parcels greedily by weight: quantities are split across parcels with their line totals and taxes scaled to the units in each, and a single unit heavier than the limit gets a parcel of its own (where the method is then unavailable).

Source: WooCommerce code reference: WC_Cart

Package keys that WooCommerce reads from the contents of a package include data (the product object), quantity, line_total, line_subtotal, line_tax and line_subtotal_tax; the cart item key must stay unique, which is why the example appends the parcel number. A method that relies on WC()->cart->get_cart()[ $key ] (for example per-item taxes with calc_tax = per_item) must not be combined with a filter that renames the keys.

Four carts were priced through the Store API (POST /cart/update-customer with the shipping address, then GET /cart; amounts in minor units are shown here in euros). The first three use the Portugal zone with the parcel method and the classic local pickup instance:

The 6 kg cart became two parcels of 5 kg and 1 kg, each with its own selected rate, and each parcel is free because the whole cart is above 40 EUR. The fourth cart shows what the zone and the flat rate do for Germany:

Placing orders with these carts (the Store API checkout, with the rate selected through POST /cart/select-shipping-rate) produced these shipping lines on the orders, read with GET /wc/v3/orders/{id}:

The rate’s meta data (weight_kg from the plugin and Items, which add_rate() adds when package is passed) is copied into the meta data of the order’s shipping line: it is the place to put a pickup point, a delivery window or a carrier service code that a warehouse system needs. A method can also add its own order meta in woocommerce_checkout_create_order_shipping_item (classic checkout).

Source: WooCommerce docs: Store API cart

WC_Shipping::calculate_shipping_for_package() is the function that produces the rates of a package. In order:

The practical consequences: while developing a method, change the code or settings and then change something in the cart (or turn on debug mode, or save a shipping setting, which bumps the transient version) before concluding that the change has no effect; and anything a method reads that is not part of the package (a user meta, the time of day, a remote carrier API) will not invalidate the cache, so add it to the package through woocommerce_cart_shipping_packages so that it changes the hash.

add_rate() calculates the tax of a rate with the shipping tax rates of the customer’s location unless the method’s tax_status is none, the cost is zero or the method passes its own taxes. The tax class used is the option woocommerce_shipping_tax_class (inherit means the classes of the cart items; see Taxes, Coupons, Currencies and i18n). The filter woocommerce_shipping_prices_include_tax makes the entered cost gross. The test zones had no tax rates, so taxes was 0 in every output on this page.

The relevant part of the Store API cart response for the Portugal cart (two 250 g bags) was:

Source: WooCommerce docs: Store API cart

The cart response also carries needs_shipping, has_calculated_shipping, items_weight and, in totals, total_shipping and total_shipping_tax. A cart without any shipping rate keeps needs_shipping true and the Checkout block shows that no shipping options are available for the address; the shopper cannot place the order until the address changes or a zone is added.

A fulfillment is a Fulfillment object (an extension of WC_Data) with an ID, entity_type (WC_Order), entity_id (the order ID as a string), status (unfulfilled for a draft, fulfilled when sent), is_fulfilled, date_updated, date_deleted (deletes are soft) and meta data. Two tables hold them:

The meta keys WooCommerce itself uses are _items (a list of { "item_id": <order item ID>, "qty": <quantity> }), _tracking_number, _tracking_url, _shipping_provider (a provider key such as correos or ups; the folder Providers of 11.2.1 contains 79 class files, one per carrier plus the abstract base, and custom providers are stored in the taxonomy wc_fulfillment_shipping_provider) and _date_fulfilled. The order gets a computed meta _fulfillment_status: no_fulfillments, unfulfilled, partially_fulfilled or fulfilled (filter woocommerce_fulfillment_calculate_order_fulfillment_status). It does not change the order status.

The routes are registered under wc/v3 for an order:

Write operations need manage_woocommerce. The experimental wc/v4 namespace also exposes /fulfillments/providers (10.5.0). This is the run on order 213 (two 1 kg bags, with the feature enabled by wp option update woocommerce_feature_fulfillments_enabled yes; the item ID was read from the order):

Source: WooCommerce docs: REST API

Three behaviours are worth knowing. An update must resend _items: a PUT that only adds a tracking URL is rejected. The date _date_fulfilled is set by WooCommerce when a record becomes fulfilled. And the API validates structure, not remaining quantity: after two units of the 1 kg bag were fulfilled across two records, a further POST for one more unit was accepted (fulfillment 4 on an order of two units), so an integration must itself compare the sum of qty per item_id with the ordered quantity.

The order notes that WooCommerce wrote during the run were: "Order fulfillment status changed from No fulfillments to Unfulfilled.", "Fulfillment #1 created (status: Unfulfilled). Items: Single-origin beans 1 kg (pcpay test) x1. Tracking: PCT-0001.", "Order fulfillment status changed from Unfulfilled to Partially fulfilled.", "Fulfillment #2 deleted." and "Fulfillment #1 status changed from Unfulfilled to Fulfilled." The order stayed on-hold: fulfilling is not completing.

Source: WooCommerce docs: Shipping

The experiment was cleaned up afterwards: the feature option was removed, the two tables were dropped and the option woocommerce_fulfillments_db_tables_created deleted, because the feature creates its tables the first time it runs. A store that turns the feature on in production keeps them.