Changes proposed in this Pull Request:

This pull request is the beginning of the implementation of a Cost of Goods Sold feature in WooCommerce, it introduces the code and REST API changes to support programmatically setting and getting one single cost value for any product.

Changes in code API

• A new feature is incorporated (handled by FeaturesController): cost_of_goods_sold
• The following methods are added to the WC_Abstract_Legacy_Product class:
  • set_cogs_value( float $value ): void
  • get_cogs_value(): float
  • get_cogs_effective_value(): float
  • get_cogs_total_value(): float
• The following methods are added (additionally to the ones above) to the WC_Product_Variation class:
  • get_cogs_value_overrides_parent(): bool
  • set_cogs_value_overrides_parent( bool $value )
• The WC_Product_Data_Store_CPT and WC_Product_Variation_Data_Store_CPT get the modifications needed to persist the new values (see below).

Currently get_cogs_value, get_cogs_effective_value and get_cogs_total_value return all the same value, with one exception: in products that are variations, get_cogs_effective_value and get_cogs_total_value return the stored value for the variation added to the stored value for the parent product, unless set_cogs_value_overrides_parent(true) was executed.

Storage

The value set by set_cogs_value is stored as product meta using the _cogs_total_value key, but only if the feature is enabled and the value is not zero (a missing meta value for a product will be treated as equivalent to a value of zero).

The value set by set_cogs_value_overrides_parent is stored as product meta using the _cogs_value_overrides_parent key, but only if the feature is enabled and the value is true (a missing meta value for a product will be treated as equivalent to a value of false).

Changes in REST API

The following is added to the REST API schema for products and variations (/wp-json/wc/v3/products/<product id> and /wp-json/wc/v3/products/<product id>/variations endpoints, for both GET and POST requests):

{
    "cost_of_goods_sold": {
        "values": [
            {
                "defined_value": <float>
                "effective_value": <float>
            }
        ],
        "total_value": <float>,
        "defined_value_overrides_parent": <bool>
    }
}

defined_value_overrides_parent is present only for variations. effective_value and total_value are read-only fields.

In principle, for POST endpoints only one object with values is expected to be found inside values. However the endpoints code will add upp the defined_valuess of all the objects if more than one is supplied, and the result will be the value set for the product.

The POST endpoints will not modify the current value of a product being modified if no values key (or no cost_of_goods_sold key whatsoever) is present, but an empty values array will set a value of zero. Similarly, for variations the "value overrides parent" flag will not be modified if no defined_value_overrides_parent is present. Default values for new products are a cost of zero and no override for variations.

Hooks

The following filters are introduced:

• woocommerce_get_cogs_total_value: to customize the value that gets returned by get_cogs_total_value.
• woocommerce_load_cogs_value: to modify the value that gets loaded from the database for a given product.
• woocommerce_load_cogs_overrides_parent_value_flag: same as above but for the value override flag.
• woocommerce_save_cogs_value: to modify the value that gets saved to the database for a given product, or to suppress the value saving altogether.
• woocommerce_save_cogs_overrides_parent_value_flag: same as above but for the value override flag.

How to test the changes in this Pull Request:

Create a variable product with at least one variation. Let's assume their ids are $product_id and $variation_id.

You also need to enable the feature. Go to WooCommerce - Settings - Advanced - Features, check the box for "Cost of Goods Sold" and save.

Code API changes

For your convenience it's recommended to test these steps from a wp shell.

1. Load the product and verify that it has a COGS value of zero, then modify the value and verify that you can retrieve it:

$p = wc_get_product($product_id);

echo $p->get_cogs_value(); // 0
echo $p->get_cogs_effective_value(); //0
echo $p->get_cogs_total_value(); //0

$p->set_cogs_value(12.34);

echo $p->get_cogs_value(); // 12.34
echo $p->get_cogs_effective_value(); //12.34
echo $p->get_cogs_total_value(); //12.34

2. Save the product and verify that the value is persisted in the database:

$p->save();

$p2 = wc_get_product($product_id);
echo $p2->get_cogs_value(); // 12.34

echo get_post_meta($product_id, '_cogs_total_value', true); // 12.34

3. Set the value as zero, save again and verify that the meta value has disappeared from the database:

$p->set_cogs_value(0);
$p->save();

global $wpdb; echo $wpdb->get_var("SELECT COUNT(1) FROM {$wpdb->postmeta} WHERE meta_key='_cogs_total_value' AND post_id=$product_id"); // 0

// Restore state for the next test
$p->set_cogs_value(12.34);
$p->save();

4. Repeat the above steps using $variation_id instead of $product_id and using a value of 20.5 instead of 12.34. The results should be the same except that the effective and total values will have the parent value added:

$v=wc_get_product($variation_id);

$v->set_cogs_value(20.5);

echo $v->get_cogs_value(); // 20.5
echo $v->get_cogs_effective_value(); // 32.84
echo $v->get_cogs_total_value(); // 32.84

5. Set the "overrides parent" to true and verify that now the effective and total values are equal to the defined value. Also save the product and verify that the flag gets saved as expected:

echo $v->get_cogs_value_overrides_parent(); // false
$v->set_cogs_value_overrides_parent(true);
echo $v->get_cogs_value_overrides_parent(); // true

echo $v->get_cogs_value(); // 20.5
echo $v->get_cogs_effective_value(); // 20.5
echo $v->get_cogs_total_value(); // 20.5

$v->save();

echo get_post_meta($variation_id, '_cogs_value_overrides_parent', true); // 'yes'

6. Set the flag to false again, save the variation, and verify that the meta value has disappeared from the database:

$v->set_cogs_value_overrides_parent(false);
$v->save();

global $wpdb; echo $wpdb->get_var("SELECT COUNT(1) FROM {$wpdb->postmeta} WHERE meta_key='_cogs_value_overrides_parent' AND post_id=$variation_id"); // 0

Testing the REST API

Perform GET requests to the /wp-json/wc/v3/products/<product id>, /wp-json/wc/v3/products/<variation id> and /wp-json/wc/v3/products/<product id>/variations/<variation id> and verify that you get the extra cost_of_goods_sold item with the appropriate information. For the variation test with and without the "overrides parent" flag set.

Now try a POST request to /wp-json/wc/v3/products/<product id> with the following body, and verify (using the code API, the GET endpoint, or querying the database) that the related information is updated accordingly (the final value should be 32.84):

{
    "cost_of_goods_sold": {
        "values": [
            {
                "defined_value": 12.34
            },
            {
                "defined_value": 20.5
            }
        ]
    }
}

Now try two POST request to /wp-json/wc/v3/products/<product id>/variations/<variation id> with the following bodies, verify that in each case only the appropriate information (value for the first, overrides flag for the second) is updated:

{
    "cost_of_goods_sold": {
        "values": [
            {
                "defined_value": 111
            }
        ]
    }
}

{
    "cost_of_goods_sold": {
         "defined_value_overrides_parent": <true or false>
    }
}

Now try the following body in a POST request to either the product or the variation endpoint, and verify that the cost value is set to zero:

{
    "cost_of_goods_sold": {
        "values": []
    }
}

Finally, try OPTIONS requests on the endpoints and verify that the extended schema information returned is accurate.

Testing the filters

Here's scaffolding code to test the filters, you can add it at the end of woocommerce.php or as a code snippet. Try changing the return value of one filter at a time, and verifying via code API or REST API that the result is as expected:

// Set a value and save. The stored value is unchanged, value returned by get_cogs_value is what you return here.
add_filter('woocommerce_load_cogs_value', function($cogs_value, $product) {
	return $cogs_value;
}, 10, 2);

// Same as above, but for the overrides flag in a variation.
add_filter('woocommerce_load_cogs_overrides_parent_value_flag', function($cogs_value_overrides_parent, $product) {
	return $cogs_value_overrides_parent;
}, 10, 2);

// Set a value and save. What you return here is what gets saved in the database
// (f you return null nothing gets saved).
add_filter('woocommerce_save_cogs_value', function($cogs_value, $product) {
	return $cogs_value;
}, 10, 2);

// Same as above, but for the overrides flag in a variation (and you can't return -1).
add_filter('woocommerce_save_cogs_overrides_parent_value_flag', function($cogs_value_overrides_parent, $product) {
	return $cogs_value_overrides_parent;
}, 10, 2);

// What you return here is what gets returned by get_cogs_total_value.
add_filter('woocommerce_get_cogs_total_value', function($cogs_value, $product) {
	return $cogs_value;
}, 10, 2);

Testing with the feature disabled

Disable the feature in the features settings page and verify that:

• You can still invoke the new methods in product objects, but values aren't loaded from, nor persisted to the database (and you get "doing it wrong" errors).
• Products retrieved via REST API don't contain a cost_of_goods_sold key.
• A cost_of_goods_sold key passed to a POST REST API request for a product will be ignored (it will not cause any change in the product).
• The OPTIONS requests don't include a cost_of_goods_sold key in the returned schema.

Note that disabling the feature won't delete any product metadata that was created while the feature was enabled.

A note on redundancy and future-proofing

It may seem that having three different cost values (defined, effective, total) is redundant. And it is at the current stage of the project, but these three values are added to support future extension of the feature while keeping backwards compatibility. More precisely, the following additions might be added at a later point:

• Cost quantity types, so you can e.g. specify a cost as a percent of the product price instead of a fixed monetary value. Then the "effective" cost would be calculated accordingly from the defined value.
• Cost value types, so you can have more than one value for a given product (e.g. cost of materials and cost of actual manufacturing). Then the total cost would be the sum of the effective values for all the value types.

This is also the reason of the seemingly convoluted design of the cost_of_goods_sold item in the REST API schema (a values array rather than one single value).

Changelog entry

• Automatically create a changelog entry from the details below.

• This Pull Request does not require a changelog entry. (Comment required below)